tshex-cli 1.0.30 → 1.0.31

package/docs/generated-file-reference.md

@@ -63,21 +63,13 @@ contracts that adapters and services can share.
 #### Shared HTTP Files
 
 The `shared/application/http` directory groups the framework-agnostic HTTP
-boundary and the type-only specifications for common web content formats.
+boundary contracts.
 
 | File | Responsibility |
 | --- | --- |
-| `shared/application/http/handlers.ts` | Declares `HttpRequestHandler` and `HttpMiddleware`. |
 | `shared/application/http/errors.ts` | Declares `HttpError`. |
-| `shared/application/http/json-api.ts` | Type-only JSON:API v1.1 document, resource, and Atomic Operations declarations. |
-| `shared/application/http/json-web-token.ts` | Type-only JOSE/JWT declarations (JWK, JWS, JWE, JWT claims). |
-| `shared/application/http/opengraph.ts` | Type-only Open Graph, Twitter Card, and social metadata declarations. |
-
-`handlers.ts` and `errors.ts` are the only files in this directory with
-runtime code. `json-api.ts`, `json-web-token.ts`, and `opengraph.ts` contain
-compile-time structure only; they describe the shape of external formats
-without implementing parsing, validation, or serialization. Each file is
-documented in its own page under `shared/application/http/*.md`.
+
+`errors.ts` is documented in its own page under `shared/application/http/errors.md`.
 
 #### Shared Data Files
 

package/docs/library-structure.md

@@ -193,9 +193,10 @@ what exists beyond that port depends on the system that implements it.
 import { Example } from './enrollment/example-ports.ts'
 import { Student } from './enrollment/domain/students.ts'
 import { Course } from './enrollment/domain/courses.ts'
+import { Email } from './shared/domain/value-objects.ts'
 
 const example = new Example()
-const student = new Student('Ada Lovelace', 'ada@example.com')
+const student = new Student('Ada Lovelace', Email.from('ada@example.com'))
 const course = new Course('Mathematics', 'Fundamentals of algebra and calculus', 40)
 
 example.createStudent(student)

package/docs/shared/application/data.md

@@ -193,6 +193,7 @@ import type { CourseData, StudentData, InscriptionData } from './managers.ts'
 import { Course } from '../domain/courses.ts'
 import { Student } from '../domain/students.ts'
 import { Inscription } from '../domain/inscriptions.ts'
+import { Email } from '../shared/domain/value-objects.ts'
 
 export class CoursesRepository extends Repository<CourseData, Course, InMemoryDatabaseManager> {
     [property: string]: unknown
@@ -222,7 +223,7 @@ export class StudentsRepository extends Repository<StudentData, Student, InMemor
     }
 
     protected transform(data: StudentData): Student {
-        return new Student(data.name, data.email)
+        return new Student(data.name, Email.from(data.email))
     }
 
     public create(student: Student): boolean {

package/docs/shared/domain/entities.md

@@ -35,25 +35,26 @@ In the following example we model the entities of a course enrollment context.
 
 ```ts title="enrollment/domain/students.ts"
 import { Entity } from '../shared/domain/entities.ts'
+import { Email } from '../shared/domain/value-objects.ts'
 
 export class Student extends Entity {
     [property: string]: unknown
 
     constructor(
         public name: string,
-        public email: string
+        public email: Email
     ) {
         super()
     }
 
     public equals(other: Student): boolean {
-        return this.email === other.email
+        return this.email.equals(other.email)
     }
 
     public override toJSON() {
         return {
             name: this.name,
-            email: this.email
+            email: this.email.value
         }
     }
 }
@@ -121,10 +122,11 @@ export class Inscription extends Entity {
 
 The most important design decision in an entity is the identity comparison.
 
-`Student` uses `email` as the identity because two students with the same email
-represent the same person. `Course` uses `name`. `Inscription` combines the
-student and course identities — two inscriptions are the same when both the
-student and the course match.
+`Student` uses `Email` as the identity because two students with the same
+address represent the same person. `equals()` delegates to `Email.equals()` so
+the comparison rule lives in the value object. `Course` uses `name`.
+`Inscription` combines the student and course identities — two inscriptions are
+the same when both the student and the course match.
 
 > **Hint**
 > Keep `equals()` explicit and small. If the comparison starts depending on many

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",

package/readme.md

@@ -86,16 +86,13 @@ core/
 |-- shared/
 |   |-- application/
 |   |   |-- data/
+|   |   |   |-- capabilities.ts
 |   |   |   |-- drivers.ts
 |   |   |   |-- managers.ts
 |   |   |   `-- repositories.ts
 |   |   |-- events.ts
 |   |   |-- http/
-|   |   |   |-- errors.ts
-|   |   |   |-- handlers.ts
-|   |   |   |-- json-api.ts
-|   |   |   |-- json-web-token.ts
-|   |   |   `-- opengraph.ts
+|   |   |   `-- errors.ts
 |   |   |-- loggers.ts
 |   |   |-- services.ts
 |   |   `-- validations.ts
@@ -248,10 +245,6 @@ From this point on, the guide is split into dedicated documents under `docs/`.
 - [shared/application/data](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/data.md)
 - [shared/application/events.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/events.md)
 - [shared/application/http/errors.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/errors.md)
-- [shared/application/http/handlers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/handlers.md)
-- [shared/application/http/json-api.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-api.md)
-- [shared/application/http/json-web-token.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-web-token.md)
-- [shared/application/http/opengraph.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/opengraph.md)
 - [shared/application/loggers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/loggers.md)
 - [shared/application/services.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/services.md)
 - [shared/application/validations.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/validations.md)

package/docs/shared/application/http/handlers.md

@@ -1,102 +0,0 @@
-### HTTP Handlers
-
-The handler contracts define a framework-agnostic, transport-facing boundary.
-They are used when an adapter needs to describe request processing and
-cross-cutting request logic in a consistent way, without depending on a
-specific server framework.
-
-The generated template relies on the standard `Request` and `Response` types
-from the Fetch API, so adapters work directly with the platform's own APIs.
-
-#### Request Handler
-
-`HttpRequestHandler` is responsible for processing a request and returning a
-response.
-
-```ts title="shared/application/http/handlers.ts"
-export interface HttpRequestHandler {
-    handle(request: Request): Response | Promise<Response>
-}
-```
-
-In the following example we implement a handler using the standard `Request`
-and `Response` objects.
-
-```ts title="users/adapters/get-user-handler.ts"
-import { HttpRequestHandler } from '../../shared/application/http/handlers.js'
-
-export class GetUserHandler implements HttpRequestHandler {
-    public handle(request: Request): Response {
-        const id = new URL(request.url).pathname.split('/').at(-1)
-
-        return Response.json({ data: { id } }, { status: 200 })
-    }
-}
-```
-
-Using the standard `Request` and `Response` types means the adapter relies on
-the platform's own APIs, such as `request.url`, `request.headers`, and
-`Response.json`. The shape of the JSON body itself, when the adapter follows
-JSON:API, is described by the document types in
-`shared/application/http/json-api.md`.
-
-`handle()` can be synchronous or asynchronous; both `Response` and
-`Promise<Response>` are valid return types, so an adapter that awaits a
-database call satisfies the same contract as one that returns immediately.
-
-#### Middleware
-
-`HttpMiddleware` is responsible for running logic before or around the
-handler.
-
-```ts title="shared/application/http/handlers.ts"
-export interface HttpMiddleware {
-    process(
-        request: Request,
-        handler: HttpRequestHandler,
-    ): Response | Promise<Response>
-}
-```
-
-Now that the handler exists, middleware can wrap it.
-
-```ts title="users/adapters/request-logger.ts"
-import {
-    HttpMiddleware,
-    HttpRequestHandler,
-} from '../../shared/application/http/handlers.js'
-
-export class RequestLoggerMiddleware implements HttpMiddleware {
-    public async process(
-        request: Request,
-        handler: HttpRequestHandler,
-    ): Promise<Response> {
-        void request
-        return handler.handle(request)
-    }
-}
-```
-
-This middleware passes the request through unchanged, showing where
-cross-cutting behavior belongs in the generated HTTP abstraction. A
-short-circuiting middleware, such as an authentication guard, follows the same
-shape but returns a `Response` (for example built from
-`shared/application/http/errors.md`'s `HttpError`) without calling
-`handler.handle()`.
-
-> **Note**
-> The handler contracts define the minimum boundary for adapters. Routing,
-> middleware chaining/composition, and status code policies beyond
-> `HttpError` are the responsibility of the concrete transport.
-
-#### Example Flow
-
-```mermaid
-flowchart LR
-    request[Request] --> middleware[Middleware]
-    middleware --> handler[Handler]
-    handler --> response["Response body"]
-```
-
-This flow keeps the transport boundary explicit while leaving framework
-choices to the adapter layer.

package/docs/shared/application/http/json-api.md

@@ -1,235 +0,0 @@
-### JSON:API
-
-`json-api.ts` declares a type-only implementation of the
-[JSON:API v1.1](https://jsonapi.org/format/) specification, including the
-[Atomic Operations extension](https://jsonapi.org/ext/atomic/). It gives an
-adapter a shared vocabulary for request and response bodies without forcing a
-particular server framework.
-
-This module has no runtime code. It only describes compile-time structure;
-rules that depend on runtime values, URI validity, document-wide uniqueness,
-full linkage, HTTP semantics, or member-name character validation still
-require explicit checks in the adapter.
-
-#### Resource Identifiers
-
-A resource is referenced in one of two ways, depending on whether the server
-has assigned it a permanent id yet.
-
-| Type | Option | Required members |
-| --- | --- | --- |
-| `JsonApiPersistedResourceIdentifier` | Server-assigned id | `type`, `id` |
-| `JsonApiLocalResourceIdentifier` | Client-assigned local id, not yet persisted | `type`, `lid` |
-
-`JsonApiResourceIdentifier` is the union of both.
-
-```ts
-import type { JsonApiResourceIdentifier } from '../../../shared/application/http/json-api.js'
-
-const persisted: JsonApiResourceIdentifier<'users'> = { type: 'users', id: '1' }
-const local: JsonApiResourceIdentifier<'users'> = { type: 'users', lid: 'tmp-1' }
-```
-
-Resource linkage (`JsonApiResourceLinkage`) is either a single identifier or
-`null` (`JsonApiToOneLinkage`), or an array of identifiers
-(`JsonApiToManyLinkage`).
-
-#### Resource Objects
-
-A resource object has the same persisted-versus-local split as its
-identifier.
-
-| Type | Option | `id` | `lid` |
-| --- | --- | --- | --- |
-| `JsonApiResourceObject` | Server-originated resource | required | optional |
-| `JsonApiNewResourceObject` | Client-originated resource without a server id | never | optional |
-
-`JsonApiCreateResourceObject` is the union accepted by create requests, since
-a client is allowed to submit a client-generated id.
-
-```ts title="users/adapters/get-user-handler.ts"
-import { HttpRequestHandler } from '../../shared/application/http/handlers.js'
-import {
-    JsonApiSingleResourceDocument,
-    JsonApiResourceObject,
-} from '../../shared/application/http/json-api.js'
-
-type UserAttributes = { email: string }
-type UserResource = JsonApiResourceObject<'users', UserAttributes>
-
-export class GetUserHandler implements HttpRequestHandler {
-    public handle(request: Request): Response {
-        const id = new URL(request.url).pathname.split('/').at(-1) ?? ''
-
-        const body: JsonApiSingleResourceDocument<UserResource> = {
-            data: {
-                type: 'users',
-                id,
-                attributes: { email: 'ada@example.com' },
-            },
-        }
-
-        return Response.json(body, { status: 200 })
-    }
-}
-```
-
-#### Relationships
-
-`JsonApiRelationship` requires at least one of `links`, `data`, or `meta`, per
-the base specification. Two narrower aliases fix the shape of `data`:
-
-| Type | `data` shape |
-| --- | --- |
-| `JsonApiToOneRelationship` | single identifier or `null` |
-| `JsonApiToManyRelationship` | array of identifiers |
-
-```ts
-import type {
-    JsonApiToOneRelationship,
-    JsonApiToManyRelationship,
-} from '../../../shared/application/http/json-api.js'
-
-const author: JsonApiToOneRelationship<{ type: 'authors' }> = {
-    data: { type: 'authors', id: '9' },
-}
-
-const comments: JsonApiToManyRelationship<{ type: 'comments' }> = {
-    data: [{ type: 'comments', id: '1' }, { type: 'comments', id: '2' }],
-}
-```
-
-#### Documents
-
-`JsonApiDocument` is a discriminated union over which top-level member is
-required. Exactly one of these three shapes is valid at a time:
-
-| Type | Required top-level member | Use |
-| --- | --- | --- |
-| `JsonApiDataDocument` | `data` | success responses returning resources |
-| `JsonApiErrorDocument` | `errors` (non-empty) | failure responses |
-| `JsonApiMetaDocument` | `meta` | responses with no primary data, such as a heartbeat |
-
-`JsonApiDataDocument` itself is narrowed by four ready-made aliases depending
-on what `data` contains:
-
-| Alias | `data` shape |
-| --- | --- |
-| `JsonApiSingleResourceDocument` | resource or `null` |
-| `JsonApiResourceCollectionDocument` | array of resources |
-| `JsonApiSingleIdentifierDocument` | identifier or `null` |
-| `JsonApiIdentifierCollectionDocument` | array of identifiers |
-| `JsonApiRelationshipDocument` | any resource linkage |
-
-```ts
-import type {
-    JsonApiErrorDocument,
-    JsonApiMetaDocument,
-} from '../../../shared/application/http/json-api.js'
-
-const notFound: JsonApiErrorDocument = {
-    errors: [{ status: '404', title: 'Not Found' }],
-}
-
-const heartbeat: JsonApiMetaDocument<{ status: string }> = {
-    meta: { status: 'ok' },
-}
-```
-
-#### Request Documents
-
-Three request-only document shapes fix `data` to exactly what each operation
-accepts:
-
-| Type | `data` shape | Use |
-| --- | --- | --- |
-| `JsonApiCreateDocument` | `JsonApiCreateResourceObject` | `POST` requests |
-| `JsonApiUpdateDocument` | `JsonApiResourceObject` | `PATCH` requests |
-| `JsonApiRelationshipUpdateDocument` | resource linkage | relationship endpoints |
-
-`JsonApiQueryParameters` describes the standard `include`, `sort`, `filter`,
-and `page` query members, plus the `fields[TYPE]`, `filter[FIELD]`, and
-`page[FIELD]` bracketed member-name patterns.
-
-#### Errors
-
-`JsonApiError` requires at least one of `id`, `links`, `status`, `code`,
-`title`, `detail`, `source`, or `meta`.
-
-```ts
-import type { JsonApiError } from '../../../shared/application/http/json-api.js'
-
-const validationError: JsonApiError = {
-    status: '422',
-    title: 'Invalid Attribute',
-    detail: 'email must be a valid address',
-    source: { pointer: '/data/attributes/email' },
-}
-```
-
-#### Atomic Operations Extension
-
-The Atomic Operations extension adds a request document that carries one or
-more operations, and a response document that carries their results. Every
-operation targets either a resource or a relationship, and every operation
-uses exactly one of three op codes. `JsonApiAtomicStrictOperation` is the
-union of the seven concrete shapes that combination produces:
-
-| Type | `op` | Target | `data` |
-| --- | --- | --- | --- |
-| `JsonApiAtomicAddResourceOperation` | `'add'` | resource (`ref` optional, `href` optional) | resource to create |
-| `JsonApiAtomicUpdateResourceOperation` | `'update'` | resource | resource to replace |
-| `JsonApiAtomicRemoveResourceOperation` | `'remove'` | resource (required) | none |
-| `JsonApiAtomicUpdateToOneRelationshipOperation` | `'update'` | relationship (required) | identifier or `null` |
-| `JsonApiAtomicAddToManyRelationshipOperation` | `'add'` | relationship (required) | identifier array |
-| `JsonApiAtomicUpdateToManyRelationshipOperation` | `'update'` | relationship (required) | identifier array |
-| `JsonApiAtomicRemoveFromManyRelationshipOperation` | `'remove'` | relationship (required) | identifier array |
-
-A target is expressed through `ref` (a `JsonApiAtomicResourceRef` or
-`JsonApiAtomicRelationshipRef`) or through `href`, never both at once
-(`JsonApiExclusive`).
-
-```ts title="users/adapters/atomic-operations-handler.ts"
-import {
-    JsonApiAtomicOperationsDocument,
-    JsonApiAtomicResultsDocument,
-    JsonApiAtomicStrictOperation,
-} from '../../shared/application/http/json-api.js'
-
-const request: JsonApiAtomicOperationsDocument<JsonApiAtomicStrictOperation> = {
-    'atomic:operations': [
-        { op: 'add', href: '/users', data: { type: 'users', attributes: { email: 'ada@example.com' } } },
-        { op: 'update', ref: { type: 'users', id: '1' }, data: { type: 'users', id: '1', attributes: { email: 'ada@lovelace.dev' } } },
-        { op: 'remove', ref: { type: 'users', id: '2' } },
-        { op: 'update', ref: { type: 'users', id: '1', relationship: 'team' }, data: { type: 'teams', id: '9' } },
-        { op: 'add', ref: { type: 'teams', id: '9', relationship: 'members' }, data: [{ type: 'users', id: '1' }] },
-    ],
-}
-
-const response: JsonApiAtomicResultsDocument = {
-    'atomic:results': [{ data: { type: 'users', id: '1' } }, {}, {}, {}, {}],
-}
-```
-
-`JsonApiAtomicRequestDocument` and `JsonApiAtomicResponseDocument` are the
-named aliases for the request and response side of the extension; the latter
-is a union of `JsonApiAtomicResultsDocument` and `JsonApiErrorDocument`, since
-a batch of operations can still fail as a whole.
-
-#### Extension And `@`-Members
-
-`JsonApiExtensionMembers` and `JsonApiAtMembers` compose extension-namespaced
-(`'ext:member'`) and meta (`'@member'`) properties through intersections, for
-custom or third-party JSON:API extensions beyond Atomic Operations.
-
-```ts
-import type { JsonApiExtensionMembers, JsonApiResourceObject } from '../../../shared/application/http/json-api.js'
-
-type VersionedResource = JsonApiResourceObject<'users'> &
-    JsonApiExtensionMembers<'version', { id: string }>
-```
-
-> **Hint**
-> These declarations only provide compile-time structure. Rules that depend on
-> runtime values, URI validity, document-wide uniqueness, or member-name
-> character validation still require explicit checks in the adapter.

package/docs/shared/application/http/json-web-token.md

@@ -1,209 +0,0 @@
-### JSON Web Tokens
-
-`json-web-token.ts` declares a type-only implementation of the JOSE and JWT
-family of RFCs (JWS, JWE, JWK, JWT, and related extensions such as DPoP and
-selective disclosure). It lets an adapter describe tokens and keys precisely
-without depending on a specific JOSE library's own types.
-
-This module has no runtime implementation. Pair it with a concrete JOSE
-library (for signing, encryption, or verification) and use these types to
-annotate its inputs and outputs.
-
-#### Branded Wire Values
-
-Wire-format primitives are branded so a plain `string` cannot be passed where
-an encoded value is expected: `Base64Url`, `Base64`, `NumericDate`,
-`StringOrURI`, `UriString`, `MediaType`, and `KeyId`. `BinaryData` is the
-union `ArrayBuffer | Uint8Array` used wherever a JOSE library accepts raw
-bytes.
-
-#### JSON Web Keys
-
-Every JWK shares `JwkCommonParameters` (`kty`, `use`, `key_ops`, `alg`, `kid`,
-the `x5*` certificate members, and the OpenID Federation `iat`/`nbf`/`exp`/
-`revoked` members). `JwkKeyType` (`kty`) then selects one of five key-family
-options, each with a public and a private variant where the family supports
-one:
-
-| `kty` | Curve/size parameter | Public type | Private type |
-| --- | --- | --- | --- |
-| `'EC'` | `EcCurve` (`P-256`, `P-384`, `P-521`, `secp256k1`) | `EcPublicJwk` (`x`, `y`) | `EcPrivateJwk` (adds `d`) |
-| `'RSA'` | — | `RsaPublicJwk` (`n`, `e`) | `RsaPrivateJwk` (adds `d`, `p`, `q`, `dp`, `dq`, `qi`, `oth`) |
-| `'oct'` | — | — (symmetric only) | `OctJwk` (`k`) |
-| `'OKP'` | `OkpCurve` (`Ed25519`, `Ed448`, `X25519`, `X448`) | `OkpPublicJwk` (`x`) | `OkpPrivateJwk` (adds `d`) |
-| `'AKP'` | `MldsaAlgorithm` (`ML-DSA-44`/`65`/`87`) | `AkpPublicJwk` (`pub`) | `AkpPrivateJwk` (adds `priv`) |
-
-`PublicJwk` and `PrivateJwk` are the unions across all five families;
-`JsonWebKey` is `PublicJwk | PrivateJwk`.
-
-```ts
-import type { EcPublicJwk, RsaPrivateJwk, OctJwk } from '../../../shared/application/http/json-web-token.js'
-
-const ecKey: EcPublicJwk = { kty: 'EC', crv: 'P-256', x: '...' as Base64Url, y: '...' as Base64Url }
-const rsaKey: RsaPrivateJwk = { kty: 'RSA', n: '...' as Base64Url, e: '...' as Base64Url, d: '...' as Base64Url }
-const symmetricKey: OctJwk = { kty: 'oct', k: '...' as Base64Url }
-```
-
-`JsonWebKeySet` wraps a `keys` array of mixed key types; `PublicJsonWebKeySet`
-narrows that array to public keys only, for a key set safe to publish. A
-thumbprint (`JwkThumbprint`) is a `Base64Url`; `JwkThumbprintUri` is the
-`urn:ietf:params:oauth:jwk-thumbprint:` URI form.
-
-#### Headers
-
-`JoseCommonHeaderParameters` covers the parameters shared by both header
-kinds (`jku`, `jwk`, `kid`, the `x5*` members, `typ`, `cty`, `crit`).
-`JwsHeaderParameters` and `JweHeaderParameters` extend it with the two
-distinct options:
-
-| Type | Required members | Extra members |
-| --- | --- | --- |
-| `JwsHeaderParameters` | `alg: JwsAlgorithm` | `b64`, `ppt`, `url`, `nonce`, `svt`, `jwt`, `client_id`, `trust_chain`, `peer_trust_chain` |
-| `JweHeaderParameters` | `alg: JweKeyManagementAlgorithm`, `enc: JweContentEncryptionAlgorithm` | `zip`, `epk`, `apu`, `apv`, `iv`, `tag`, `p2s`, `p2c`, replicated `iss`/`sub`/`aud`, `url`, `nonce` |
-
-`JwsHeader<CustomHeader>` and `JweHeader<CustomHeader>` intersect the
-respective parameters with a caller-supplied custom header shape.
-
-#### Serializations
-
-A JWS or a JWE can be represented four ways: as a single delimited string
-(compact), or as JSON with either one signer/recipient inlined (flattened) or
-several (general).
-
-| Type | Kind | Shape |
-| --- | --- | --- |
-| `CompactJws` | JWS, compact | `` `${string}.${string}.${string}` `` branded string |
-| `GeneralJwsJsonSerialization` | JWS, JSON, general | `payload` + `signatures[]` |
-| `FlattenedJwsJsonSerialization` | JWS, JSON, flattened | `payload` + one signature inlined |
-| `CompactJwe` | JWE, compact | `` `${string}.${string}.${string}.${string}.${string}` `` branded string |
-| `GeneralJweJsonSerialization` | JWE, JSON, general | shared members + `recipients[]` |
-| `FlattenedJweJsonSerialization` | JWE, JSON, flattened | shared members + one recipient inlined |
-
-`JwsJsonSerialization` and `JweJsonSerialization` are the general/flattened
-unions for each. `UnsecuredCompactJws` types the `alg: 'none'` compact form
-(`` `${string}.${string}.` `` — an empty signature segment).
-
-```ts
-import type { CompactJws, FlattenedJwsJsonSerialization } from '../../../shared/application/http/json-web-token.js'
-
-const compact = 'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiIxIn0.c2ln' as CompactJws
-
-const flattened: FlattenedJwsJsonSerialization = {
-    payload: 'eyJzdWIiOiIxIn0' as Base64Url,
-    protected: 'eyJhbGciOiJFUzI1NiJ9' as Base64Url,
-    signature: 'c2ln' as Base64Url,
-}
-```
-
-`DecodedJws` and `DecodedJwe` describe a decoded token's structure;
-`DecodedJwt` is their union, discriminated by a `kind: 'JWS' | 'JWE'` tag.
-`CompactJwt` is `CompactJws | CompactJwe`, matching how RFC 7519 allows a JWT
-to use either serialization.
-
-#### JWT Claims
-
-`JwtRegisteredClaims` covers the seven RFC 7519 claims (`iss`, `sub`, `aud`,
-`exp`, `nbf`, `iat`, `jti`). `IanaRegisteredJwtClaims` extends it with every
-claim name currently registered by IANA (OpenID Connect profile claims, SIP,
-CDNI, GNAP, EAT, RATS, RFC 9901 selective-disclosure claims, OpenID
-Federation claims, and more), so `JwtClaims<CustomClaims>` covers arbitrary
-custom claims through intersection while still typing every standard one.
-
-Four ready-made profiles fix `JwtRegisteredClaims` members to `required`
-where the profile mandates them, as distinct implementation options for
-common token kinds:
-
-| Type | Profile | Required beyond the base seven |
-| --- | --- | --- |
-| `OpenIdConnectIdTokenClaims` | OIDC ID Token | `iss`, `sub`, `aud`, `exp`, `iat` |
-| `OAuth2JwtAccessTokenClaims` | RFC 9068 OAuth 2.0 access token | `iss`, `exp`, `aud`, `sub`, `client_id`, `iat`, `jti` |
-| `DpopProofClaims` | RFC 9449 DPoP proof | `jti`, `htm`, `htu`, `iat` |
-| `SdJwtClaims` | RFC 9901 SD-JWT | none beyond `IanaRegisteredJwtClaims`, adds `_sd`/`_sd_alg` |
-
-```ts title="users/adapters/verify-access-token.ts"
-import {
-    JwsVerifier,
-    OAuth2JwtAccessTokenClaims,
-    CompactJws,
-    JsonWebKey,
-} from '../../shared/application/http/json-web-token.js'
-
-export function verifyAccessToken(
-    verifier: JwsVerifier,
-    token: CompactJws,
-    key: JsonWebKey,
-) {
-    return verifier.verify<OAuth2JwtAccessTokenClaims>(token, key)
-}
-```
-
-`SdJwtDisclosure`, `SdJwt`, and `SdJwtPresentation` brand the three distinct
-string forms used by selective disclosure: a single disclosure, an issued
-SD-JWT, and a presentation with disclosures appended.
-
-#### Service Contracts
-
-An adapter implements these interfaces against a concrete JOSE library. Each
-one exposes a distinct operation:
-
-| Contract | Method(s) | Responsibility |
-| --- | --- | --- |
-| `JwtDecoder` | `decode()` | Parse a compact token into a `DecodedJwt` without necessarily validating it. |
-| `JwsSigner` | `signCompact()`, `signFlattened()` | Produce a JWS in either serialization. |
-| `JwsVerifier` | `verify()` | Validate a JWS and return a `JwtValidationResult`. |
-| `JweEncrypter` | `encryptCompact()`, `encryptFlattened()` | Produce a JWE in either serialization. |
-| `JweDecrypter` | `decrypt()` | Decrypt a JWE back into `BinaryData`. |
-| `JwkThumbprinter` | `thumbprint()`, `thumbprintUri()` | Compute an RFC 7638 thumbprint, plain or as a URI. |
-| `JwksResolver` | `resolve()`, `select()` | Fetch a JWK Set and pick the key matching a header's `kid`/`x5t`/`x5t#S256`. |
-
-```ts
-import type { JwkThumbprinter, JsonWebKey } from '../../../shared/application/http/json-web-token.js'
-
-function fingerprint(thumbprinter: JwkThumbprinter, key: JsonWebKey) {
-    return thumbprinter.thumbprintUri(key)
-}
-```
-
-#### Validating A Token
-
-`JwtValidationResult` is the outcome of checking a token against a
-`JwtValidationPolicy` (`issuers`, `audiences`, `subjects`, `algorithms`,
-`requiredClaims`, `clockToleranceSeconds`, `maxTokenAgeSeconds`, `typ`). It
-has exactly two implementation options, discriminated by `valid`:
-
-| Type | `valid` | Payload |
-| --- | --- | --- |
-| `JwtValidationSuccess` | `true` | `value: DecodedJws<Claims>` |
-| `JwtValidationFailure` | `false` | `code`, `message`, optional `cause` |
-
-`JwtValidationFailure['code']` enumerates the recognized rejection reasons:
-`'malformed'`, `'unsupported_serialization'`, `'unsupported_algorithm'`,
-`'invalid_signature'`, `'decryption_failed'`, `'expired'`, `'not_active'`,
-`'issued_in_future'`, `'issuer_mismatch'`, `'audience_mismatch'`,
-`'subject_mismatch'`, `'missing_claim'`, `'critical_header_unsupported'`, and
-`'policy_rejected'` (plus an open string for adapter-specific codes).
-
-```ts
-import type { JwtValidationResult } from '../../../shared/application/http/json-web-token.js'
-
-function describeResult(result: JwtValidationResult): string {
-    if (result.valid) {
-        return `ok, subject=${result.value.claims.sub}`
-    }
-
-    return `rejected: ${result.code}`
-}
-```
-
-#### Registry Metadata
-
-`JoseAlgorithmRegistryEntry`, `JoseHeaderParameterRegistryEntry`, and
-`JwtClaimRegistryEntry` type the shape of a row describing an algorithm, a
-header parameter, or a claim, for adapters that want to render or validate
-against IANA's own registry data instead of hardcoding the unions above.
-
-> **Hint**
-> This module has no runtime implementation. Choose a JOSE library, then use
-> `JwsSigner`/`JwsVerifier`/`JweEncrypter`/`JweDecrypter`/`JwtDecoder` to
-> annotate its inputs and outputs so the rest of the codebase stays independent
-> from that library's own types.

package/docs/shared/application/http/opengraph.md

@@ -1,161 +0,0 @@
-### Open Graph
-
-`opengraph.ts` declares a type-only implementation of the
-[Open Graph protocol](https://ogp.me/), the Twitter Card meta tags, and
-Facebook's compatibility extensions. It is used when an adapter needs to build
-or read the social-sharing metadata of a page.
-
-This module has no runtime values or implementations, including no HTML
-rendering. Use it to build the data and a separate template or renderer to
-emit the actual `<meta>` tags.
-
-#### Base Shape
-
-Every Open Graph object shares `OpenGraphBase<TType>`: the required `title`,
-`type`, `images` (`OneOrMore<OpenGraphImage>`, first has precedence), and
-`url`, plus the optional `audio`, `description`, `determiner`, `locale`,
-`alternateLocales`, `siteName`, and `videos`. `OpenGraphObjectExtensions`
-adds an optional `extensions` map for CURIE-namespaced custom properties
-(`'product:color'`, etc.), kept as opaque strings.
-
-#### Standard Object Types
-
-`OpenGraphType` selects one of thirteen standard types
-(`OpenGraphStandardType`) or a custom CURIE type
-(`OpenGraphCustomType`, e.g. `'product:item'`). Each standard type has its
-own interface adding the fields that type requires:
-
-| `type` | Interface | Extra fields |
-| --- | --- | --- |
-| `'website'` | `OpenGraphWebsite` | none |
-| `'article'` | `OpenGraphArticle` | `publishedTime`, `modifiedTime`, `expirationTime`, `authors`, `section`, `tags` |
-| `'book'` | `OpenGraphBook` | `authors`, `isbn`, `releaseDate`, `tags` |
-| `'profile'` | `OpenGraphProfile` | `firstName`, `lastName`, `username`, `gender` |
-| `'music.song'` | `OpenGraphMusicSong` | `duration`, `albums`, `musicians` |
-| `'music.album'` | `OpenGraphMusicAlbum` | `songs`, `musicians`, `releaseDate` |
-| `'music.playlist'` | `OpenGraphMusicPlaylist` | `songs`, `creator` |
-| `'music.radio_station'` | `OpenGraphMusicRadioStation` | `creator` |
-| `'video.movie'` | `OpenGraphVideoMovie` | `actors`, `directors`, `writers`, `duration`, `releaseDate`, `tags` (`OpenGraphVideoMetadata`) |
-| `'video.episode'` | `OpenGraphVideoEpisode` | `OpenGraphVideoMetadata` + `series` |
-| `'video.tv_show'` | `OpenGraphVideoTvShow` | `OpenGraphVideoMetadata` |
-| `'video.other'` | `OpenGraphVideoOther` | `OpenGraphVideoMetadata` |
-| `'payment.link'` | `OpenGraphPaymentLink` | `paymentDescription`, `currency`, `amount`, `expiresAt`, `paymentStatus`, `paymentId`, `successUrl` (marked beta by the protocol) |
-| CURIE type | `OpenGraphCustomObject` | none beyond the base shape |
-
-`OpenGraphMetadata` is the union of all fourteen. Building one selects the
-type through the discriminant and, from there, TypeScript narrows to that
-type's own extra fields.
-
-```ts title="users/adapters/user-profile-metadata.ts"
-import { OpenGraphProfile } from '../../shared/application/http/opengraph.js'
-
-export function buildProfileMetadata(username: string): OpenGraphProfile {
-    return {
-        type: 'profile',
-        title: username,
-        url: `https://example.com/users/${username}`,
-        images: [{ url: `https://example.com/users/${username}/avatar.png` }],
-        username,
-    }
-}
-```
-
-```ts title="users/adapters/article-metadata.ts"
-import { OpenGraphArticle } from '../../shared/application/http/opengraph.js'
-
-export function buildArticleMetadata(slug: string): OpenGraphArticle {
-    return {
-        type: 'article',
-        title: 'How context ports work',
-        url: `https://example.com/blog/${slug}`,
-        images: [{ url: `https://example.com/blog/${slug}/cover.png` }],
-        publishedTime: new Date().toISOString(),
-        tags: ['architecture', 'typescript'],
-    }
-}
-```
-
-`OpenGraphPaymentStatus` (`'PENDING' | 'PAID' | 'FAILED' | 'EXPIRED'`) types
-`OpenGraphPaymentLink['paymentStatus']`.
-
-#### Twitter Cards
-
-`TwitterCardType` selects one of four card layouts. `TwitterCardBase<TCard>`
-carries the members every card shares (`site`, `siteId`, `creator`,
-`creatorId`, `title`, `description`); each concrete card adds the fields that
-layout needs:
-
-| `card` | Interface | Extra/required fields |
-| --- | --- | --- |
-| `'summary'` | `TwitterSummaryCard` | optional `image` |
-| `'summary_large_image'` | `TwitterSummaryLargeImageCard` | optional `image` |
-| `'player'` | `TwitterPlayerCard` | required `image`, `player`, `playerWidth`, `playerHeight`; optional `playerStream`, `playerStreamContentType` |
-| `'app'` | `TwitterAppCard` | optional `country`, `iphone`, `ipad`, `googlePlay` (each `TwitterAppPlatform`) |
-
-`TwitterCardMetadata` is the union of all four.
-
-```ts
-import type { TwitterPlayerCard } from '../../../shared/application/http/opengraph.js'
-
-const playerCard: TwitterPlayerCard = {
-    card: 'player',
-    image: { url: 'https://example.com/videos/1/thumb.png' },
-    player: 'https://example.com/videos/1/embed',
-    playerWidth: 640,
-    playerHeight: 360,
-}
-```
-
-#### Raw Meta Tag Representation
-
-`OpenGraphMetaTag`/`TwitterMetaTag` are the flat `property`/`content` and
-`name`/`content` tag forms closer to the actual `<meta>` markup, for a
-renderer that emits tags directly instead of consuming the structured
-objects above.
-
-| Tag family | Type | Attribute pair |
-| --- | --- | --- |
-| Open Graph (standard) | `OpenGraphStandardMetaTag` | `property`/`content`, e.g. `'og:title'` |
-| Open Graph (custom) | `OpenGraphCustomMetaTag` | any `` `${string}:${string}` `` property |
-| Twitter | `TwitterMetaTag` | `name`/`content`, e.g. `'twitter:card'` |
-| Facebook | `FacebookMetaTag` | `PropertyMetaTag<'fb:app_id'>` |
-| Standard HTML | `StandardHtmlMetaTag` | `'description'` \| `'theme-color'` |
-
-`SocialMetaTag` is the union of all five families. `CanonicalLinkTag` types
-the `<link rel="canonical">` element separately, since it is not a `<meta>`
-tag.
-
-#### Aggregate Document
-
-Two document shapes cover the two stages of building a page's social
-metadata:
-
-| Type | Shape | Use |
-| --- | --- | --- |
-| `SocialMetadataDocument` | `head?`, `openGraph` (required), `twitter?`, `facebook?` | Structured data a service builds before rendering |
-| `RawSocialMetadataDocument` | `title?`, `meta: SocialMetaTag[]`, `links?: CanonicalLinkTag[]` | The rendered, tag-list form a template consumes |
-
-```ts title="users/adapters/social-metadata-document.ts"
-import {
-    SocialMetadataDocument,
-    OpenGraphProfile,
-} from '../../shared/application/http/opengraph.js'
-
-export function buildSocialMetadata(profile: OpenGraphProfile): SocialMetadataDocument {
-    return {
-        head: { title: profile.title, description: profile.description },
-        openGraph: profile,
-        twitter: { card: 'summary', title: profile.title },
-    }
-}
-```
-
-Converting a `SocialMetadataDocument` into a `RawSocialMetadataDocument` is
-the responsibility of a renderer, which flattens each structured field into
-its corresponding `SocialMetaTag` entries; that conversion is not implemented
-by this module.
-
-> **Hint**
-> This module has no runtime implementation, including no HTML rendering. Use
-> `OpenGraphMetadata` to build the data and a separate template or renderer to
-> emit the `<meta>` tags described by `OpenGraphMetaTag`/`TwitterMetaTag`.