Zum Hauptinhalt springen

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
Contract2026-05-plexon-federation-v3
Entryimport { … } 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 / typeMeaning
UserSchemaDIC user
CompanySchemaTenant
CollectionSchemaUser-facing project
BindingSchemaProduct ↔ Collection link
CollectionMemberSchemaMembership row
PLATFORM_PRODUCT_IDSKnown product id literals

Id helpers (PlatformProjectIdSchema, …) keep path params honest.

Wire areas (request/response Zod)​

AreaStart here
UpsertPlatformProjectUpsertRequestSchema / ResponseSchema, resolveExternalProjectId
OriginORIGIN_SCHEMAS_BY_PRODUCT, originSchemaForProduct
Accessible CollectionsAccessibleCollectionsResponseSchema
Members / invitesCollectionMember* / CollectionInvite*
Auth / profile / usageValidateCredentials*, Profile*, UsageEvent*
Health / registryFederationHealthSchema, PlatformProductsRegistryResponseSchema
ErrorsFederationErrorBodySchema

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 browserServer only
Types, enums, pure helpers that need no secretbuildFederationHeaders with a real secret
UI that displays Collection names you already fetchedCalls that attach X-Service-Secret

What usually goes wrong​

MistakeFix
Deep-importing dist/... internalsStick to package exports
Skipping Zod parse on upsertValidate, then write
Hard-coded /api/platform/... stringsUse path constants
Bundling the service secret into client codeKeep headers on the BFF

See also: REST · Auth · dic-app