@nxgt/shared-graphql 1.5.0 → 1.5.1

package/README.md

@@ -4,18 +4,31 @@ The GraphQL layer: Yoga + Hono wiring, the federation subgraph builder, shared
 scalars and directives, dataloaders, subscriptions over Redis, upload handling,
 and the SDL every service merges into its own schema.
 
+## Install
+
+```bash
+bun add @nxgt/shared-graphql
+```
+
+Public on npmjs; no token needed to install. TypeScript is a peer, pinned to
+`^6.0.3` across every `@nxgt/*` package — the set is unsatisfiable if one of
+them widens it. **`stx-sdk` is a required peer** (`>=1.1.0`).
+
 ## Subpaths
 
 | Subpath | What is in it |
 | --- | --- |
-| `@nxgt/shared-graphql` | server wiring, scalars, utils, context types |
-| `@nxgt/shared-graphql/security` | the `@policy` directive and its validation |
+| `@nxgt/shared-graphql` | server wiring, scalars, utils, context types, plugins |
+| `@nxgt/shared-graphql/security` | `PolicyEvaluationService` / `evaluateFromRules` — wraps `@nxgt/security/policy` for a Yoga schema |
 
 ## The shared SDL ships in `graphql/`, not in `dist/`
 
 `bun build` bundles code and nothing else, so the `.graphqls` files live in
-their own published directory. Point your codegen and your schema loader at
-**`SHARED_SCHEMA_PATH`**, which this package resolves against its own root:
+their own published directory (`graphql/directives`, `graphql/scalars`,
+`graphql/schema`). Point your codegen and your schema loader at
+**`SHARED_SCHEMA_PATH`**, which this package resolves against its own root by
+walking up to the nearest `package.json` — the bundle is `dist/index.js`, the
+source is `src/utils/schema.utils.ts`, and no single relative path serves both.
 
 ```ts
 import { loadTypeDefs, SCALAR_RESOLVERS, SHARED_SCHEMA_PATH } from '@nxgt/shared-graphql';
@@ -33,6 +46,15 @@ schema: ['./src/**/*.graphqls', SHARED_SCHEMA_PATH],
 A relative path into this package's `src/` will not work from an install — it
 is not published, and it was not there in the first place.
 
+`SHARED_TYPE_DEFS` is a string of the shared directives (`@authenticated`,
+`@policy`, `@shareable`, `@link`) plus empty root types. A subgraph that
+builds through `buildSubgraphSchema` and never loads `SHARED_TYPE_DEFS` still
+sees `@check`, because that declaration lives in `graphql/directives/` and
+rides `SHARED_SCHEMA_PATH`. A directive put *only* in `SHARED_TYPE_DEFS`
+would be invisible to exactly the schemas most likely to want it.
+
+`buildSubgraphSchema` wraps Apollo's builder and prunes unused types.
+
 ## `@check` — the permission a field requires
 
 `@authenticated` asks whether anyone is calling. `@policy` asks whether they
@@ -109,20 +131,44 @@ terms is vacuously true, so it would admit everyone while looking guarded.
 A Keto outage is never a denial: `OryUnavailable` travels up to
 `createMaskError`, which answers 503.
 
-## The context is a `TokenPrincipal`
+### A shipped directive is not a composed directive
+
+Shipping the SDL is enough for a standalone Yoga schema. It is **not** enough
+for a subgraph that federation composes. The day `@check` is used in `health`
+or `platform`, rover needs both `@composeDirective(name: "@check")` in that
+subgraph and the directive named in the subgraph's own `@link` import list.
+Without them the composition drops it silently — the supergraph SDL comes out
+valid, the field loses its check, and nothing fails.
+
+## Plugins and context
+
+| Export | What it does |
+| --- | --- |
+| `useOryAuth(ory)` | Yoga plugin: resolve the caller, set `context.user` |
+| `useKetoChecks(ory)` | Yoga plugin: per-request DataLoader for Keto, and the `@check` transformer |
+| `applyKetoChecks(schema)` | wrap an already-built schema with `@check` |
+| `useAuth()` | Yoga plugin: require a user on the context |
+| `extractJwtPlugin` | Apollo plugin: copy `request.extensions.payload` onto `context.jwt` |
 
 `GraphQLBaseContext.user` is `TokenPrincipal` — the caller as the access token
 describes them (`sub`, `uid`, `scope`). It is not `Principal`, which is the
 header-derived shape used by the REST services.
 
-`stx-sdk` is a peer, public on npmjs.
+`createYogaHono` / `honoYoga` (from this package's integrations) mount Yoga on
+Hono. `sandboxExpolorer` serves Apollo Sandbox. Subscriptions go over Redis
+(`graphql-subscriptions` is re-exported). `DataLoader` is re-exported so a
+subgraph does not take a second copy.
 
-## Install
+Uploads: the `Upload` scalar lives in this package; `graphql/scalars` ships the
+SDL.
 
-```bash
-bun add @nxgt/shared-graphql
-```
+## Things that bite
 
-Public on npmjs; no token needed to install. TypeScript is a peer, pinned to
-`^6.0.3` across every `@nxgt/*` package — the set is unsatisfiable if one of
-them widens it.
+- **`@check` on a list field is the wrong tool.** Filter before the read.
+- **Do not import `graphql-subscriptions` from `graphql-subscriptions`.** Take
+  it from this package, same reason mongoose comes from `@nxgt/shared-mongo`.
+- **The sandbox helper is spelled `sandboxExpolorer`.** That is the export
+  name. A corrected spelling is a breaking change, not a typo fix in the
+  consumer.
+- **`stx-sdk` is required.** Unlike `@nxgt/security`, this package does not
+  mark it optional.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/shared-graphql",
-	"version": "1.5.0",
+	"version": "1.5.1",
 	"license": "UNLICENSED",
 	"type": "module",
 	"main": "./dist/index.js",