All files / src/platform/gateway/decorators api-governance.decorators.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
import { SetMetadata, applyDecorators } from '@nestjs/common';
import { ApiHeader, ApiResponse, ApiTags } from '@nestjs/swagger';
 
export const PUBLIC_ROUTE_KEY = 'isPublicRoute';
export const MOBILE_ROUTE_KEY = 'isMobileRoute';
export const WEB_ROUTE_KEY = 'isWebRoute';
export const RATE_LIMIT_POLICY_KEY = 'rateLimitPolicy';
export const REQUIRE_IDEMPOTENCY_KEY = 'requiresIdempotency';
export const DEPRECATED_API_KEY = 'deprecatedApi';
export const API_USAGE_METRIC_KEY = 'apiUsageMetric';
export const API_VERSION_KEY = 'apiVersion';
 
/**
 * Marks a route as publicly accessible without authentication.
 */
export const PublicRoute = () => SetMetadata(PUBLIC_ROUTE_KEY, true);
 
/**
 * Marks a route as a mobile-facing endpoint.
 * Mobile routes enforce self-scoped access (employee can only see their own data).
 */
export const MobileRoute = () =>
  applyDecorators(
    SetMetadata(MOBILE_ROUTE_KEY, true),
    ApiHeader({
      name: 'x-client-app',
      description: 'Client application identifier',
      required: false,
    }),
  );
 
/**
 * Marks a route as a web-facing endpoint (admin/manager panels).
 */
export const WebRoute = () => SetMetadata(WEB_ROUTE_KEY, true);
 
/**
 * Applies a named rate-limit policy from ApiRateLimitPolicyService.
 */
export const RateLimitPolicy = (policyKey: string) =>
  SetMetadata(RATE_LIMIT_POLICY_KEY, policyKey);
 
/**
 * Requires an Idempotency-Key header for this endpoint.
 */
export const RequireIdempotency = () =>
  applyDecorators(
    SetMetadata(REQUIRE_IDEMPOTENCY_KEY, true),
    ApiHeader({
      name: 'Idempotency-Key',
      description: 'Client-generated unique key for idempotent requests',
      required: true,
    }),
  );
 
/**
 * Marks an API endpoint as deprecated.
 * The interceptor will add Deprecation and Sunset headers to responses.
 */
export const DeprecatedApi = (message?: string, replacedBy?: string) =>
  applyDecorators(
    SetMetadata(DEPRECATED_API_KEY, { message, replacedBy }),
    ApiHeader({
      name: 'Deprecation',
      description: 'This endpoint is deprecated',
      required: false,
    }),
  );
 
/**
 * Tags the route with a specific API version for Swagger grouping.
 */
export const ApiVersioned = (version: string = 'v1') =>
  SetMetadata(API_VERSION_KEY, version);
 
/**
 * Tags the route for usage metering (used by AiMetricsCollector etc.)
 */
export const ApiUsageMetric = (metricName: string) =>
  SetMetadata(API_USAGE_METRIC_KEY, metricName);