TypeScript · @chbrdk/plexon-federation
The DIC SDK is the TypeScript source of truth for the federation wire: Zod schemas, header helpers, path constants, OpenAPI, and the GraphQL SDL string.
| Package | @chbrdk/plexon-federation@0.2.1 |
| Contract | 2026-05-plexon-federation-v3 |
| Entry | import { … } from '@chbrdk/plexon-federation' |
This page is a curated map of the public surface. Prefer these exports over deep imports into package internals — internals are not a stability promise.
Install
npm install @chbrdk/plexon-federation@0.2.1
Artefacts also published as package subpaths:
@chbrdk/plexon-federation/openapi/federation-v3.yaml@chbrdk/plexon-federation/graphql/entities.graphql
Same bytes as the portal downloads: OpenAPI · SDL.
Contract and headers
import {
FEDERATION_CONTRACT_VERSION,
FEDERATION_SDK_VERSION,
buildFederationHeaders,
readServiceSecret,
readActorUserId,
readContractVersion,
} from '@chbrdk/plexon-federation'
const headers = buildFederationHeaders({
contractVersion: FEDERATION_CONTRACT_VERSION,
serviceSecret: process.env.PLEXON_SERVICE_SECRET!,
userId: viewerId, // omit only for non-viewer routes that truly need no actor
})
Inbound route handlers can parse the same headers with readServiceSecret / readActorUserId / readContractVersion.
Entities you will see everywhere
| Schema / type | Meaning |
|---|---|
UserSchema | DIC user |
CompanySchema | Tenant |
CollectionSchema | User-facing project |
BindingSchema | Product ↔ Collection link |
CollectionMemberSchema | Membership row |
PLATFORM_PRODUCT_IDS | Known product id literals |
Id helpers (PlatformProjectIdSchema, …) keep path params honest.
Wire areas (request/response Zod)
| Area | Start here |
|---|---|
| Upsert | PlatformProjectUpsertRequestSchema / ResponseSchema, resolveExternalProjectId |
| Origin | ORIGIN_SCHEMAS_BY_PRODUCT, originSchemaForProduct |
| Accessible Collections | AccessibleCollectionsResponseSchema |
| Members / invites | CollectionMember* / CollectionInvite* |
| Auth / profile / usage | ValidateCredentials*, Profile*, UsageEvent* |
| Health / registry | FederationHealthSchema, PlatformProductsRegistryResponseSchema |
| Errors | FederationErrorBodySchema |
Parse before you write to your database. That single habit absorbs most contract upgrades.
Descriptors and Knowledge Pack
Lane A products declare how DIC reaches them via capability descriptors (extend the descriptor table — do not fork product-id switches). Knowledge Pack helpers version the pack schema (KNOWLEDGE_PACK_SCHEMA_VERSION and related exports).
GraphQL helper
import { FEDERATION_GRAPHQL_SDL } from '@chbrdk/plexon-federation'
// Use for local Magidoc / schema checks — not as a substitute for Access Model B
Path constants
Import path builders / constants from the package (PATH_PLATFORM_*, PATH_SERVICES_*, …) instead of hard-coding URL strings in product apps. Document new paths in the portal REST page when they become public.
Browser vs server
| Safe in browser | Server only |
|---|---|
| Types, enums, pure helpers that need no secret | buildFederationHeaders with a real secret |
| UI that displays Collection names you already fetched | Calls that attach X-Service-Secret |
What usually goes wrong
| Mistake | Fix |
|---|---|
Deep-importing dist/... internals | Stick to package exports |
| Skipping Zod parse on upsert | Validate, then write |
Hard-coded /api/platform/... strings | Use path constants |
| Bundling the service secret into client code | Keep headers on the BFF |