@jesse-ska-9/api-annotations

Publish-tier annotation scheme for SKA API surface elements. Implements the upstream half of TS-036 per SPECKIT-SKA-API-002.

The package provides:

• @PublishTier(value) — TypeScript decorator applied at the route handler, DTO class, or class field level. Argument is a string-literal type constrained to 'public' | 'partner' | 'internal'; any other value fails TypeScript compilation.
• PublishTierValue — the literal union type itself, exported for downstream type narrowing.
• getPublishTier(target, propertyKey?) — metadata extraction helper that returns the tier value or undefined for unannotated elements (fail-closed inputs to the SPECKIT-SKA-API-002 §6 default behavior).

Mental model

The decorator is a classification stamp at the point of declaration. Analogous to how every document in a classified environment carries its classification level at the top of the page (UNCLASSIFIED / CONFIDENTIAL / SECRET), every SKA API surface element carries its tier at the site of declaration. A page without a stamp is treated as internal by default (SPECKIT §6 fail-closed); the sanitizer never emits an unstamped element to a lower-classification audience.

Usage

import 'reflect-metadata';
import { PublishTier } from '@jesse-ska-9/api-annotations';

@Controller('/v3/atoms')
export class AtomsController {
  @Post()
  @PublishTier('partner')
  createAtom(@Body() dto: CreateAtomDto): AtomResource {
    // ...
  }

  @Get(':id')
  @PublishTier('public')
  getAtom(@Param('id') id: string): AtomResource {
    // ...
  }

  @Delete(':id')
  // no @PublishTier → sanitizer treats as 'internal'
  deleteAtom(@Param('id') id: string): void {
    // ...
  }
}

@PublishTier('public')
export class AtomResource {
  id: string;

  @PublishTier('partner')   // property-level override
  partnerOnlyField: string;
}

Reading the metadata downstream (e.g., from a @nestjs/swagger extension):

import { getPublishTier } from '@jesse-ska-9/api-annotations';

// Class-level:
const classTier = getPublishTier(AtomResource);                // 'public'

// Method-level:
const methodTier = getPublishTier(
  AtomsController.prototype,
  'createAtom',
);                                                              // 'partner'

// Property-level:
const propTier = getPublishTier(
  AtomResource.prototype,
  'partnerOnlyField',
);                                                              // 'partner'

getPublishTier returns undefined for unannotated elements. The sanitization pipeline (SPECKIT-SKA-DEV-001 §7) treats undefined as internal per the SPECKIT-SKA-API-002 §6 fail-closed default; this package does not apply the default itself — that decision lives in the emitter, not the metadata helper, so the helper preserves the distinction between "absent" and "explicitly internal" for audit purposes.

Required TypeScript config

Consumer projects MUST set the following in their tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

These match ska-core-api's configuration per SPECKIT-SKA-API-002 §4 (NestJS as the decorator runtime). reflect-metadata MUST be imported once at application entry (typically main.ts).

Status

v0.1.0 — Phase 1 of SPECKIT-SKA-API-002 (decorator + types + metadata helper). Phase 2 (@nestjs/swagger extension that emits x-publishTier into the generated OpenAPI document) lives in ska-core-api and is gated behind this package's NPM publication.

Trade Secret Classification

This package is the upstream half of the publish-tier annotation + sanitization pipeline registered as TS-036. The combined annotation + sanitization + blacklist + fail-closed pipeline is the material trade secret; this package alone is one structural component of it. See LICENSE.md and the SPECKIT references above.

© 2023–2026 Jesse Garza. All rights reserved.