@webpieces/core-util 0.4.794 → 0.4.796

package/src/http/api-kind.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-kind.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/api-kind.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\nimport { EndpointKind, METADATA_KEYS, getEndpoints, getEndpointKinds, isApiPath } from './decorators';\n\n/**\n * API KIND — whether a contract is synchronous RPC or fire-and-forget over a queue — plus the\n * queue-naming rules that only a @PubSub contract has.\n *\n * Split out of `decorators.ts` purely for size (max-file-lines); the dependency runs ONE way,\n * api-kind -> decorators, so there is no cycle. Auth modes and endpoint shape stay in\n * `decorators.ts`; everything here is re-exported from the package barrel, so no consumer import\n * changes and there is no second spelling of anything.\n */\n\n// ============================================================\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n// ============================================================\n\n/**\n * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).\n * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)\n * schedules a Cloud Task that is later delivered to the SAME controller endpoint.\n */\nexport type ApiKind = 'rpc' | 'pubsub';\n\n/**\n * @Rpc() - marks an API class as synchronous request/response (the default kind).\n * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function Rpc(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'rpc' as ApiKind, target);\n    };\n}\n\n/**\n * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method\n * MUST return Promise<void> (a compile-time contract on the abstract API). The\n * enqueue client and the controller share this one class, exactly like RPC.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function PubSub(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'pubsub' as ApiKind, target);\n    };\n}\n\n/**\n * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default\n * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function Queue(name: string): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const overrides: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};\n        overrides[propertyKey as string] = name;\n        Reflect.defineMetadata(METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);\n    };\n}\n\n/**\n * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function getApiKind(apiClass: Function): ApiKind {\n    return (Reflect.getMetadata(METADATA_KEYS.API_KIND, apiClass) as ApiKind) ?? 'rpc';\n}\n\n/**\n * Assert the API class is of the expected kind (used by the clients: the RPC\n * client rejects a @PubSub api and vice-versa).\n * @throws Error if the kind doesn't match.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function assertApiKind(apiClass: Function, expected: ApiKind): void {\n    const actual = getApiKind(apiClass);\n    if (actual !== expected) {\n        const apiName = apiClass.name || 'Unknown';\n        throw new Error(\n            `API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +\n            `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`,\n        );\n    }\n}\n\n/**\n * Which {@link EndpointKind}s each {@link ApiKind} may declare. A @PubSub contract is delivered\n * asynchronously by definition, so `rpc` is meaningless on it; an @Rpc contract has no queue, so\n * `cloudtasks`/`cron` on it would name a queue/schedule nothing could ever deliver to. `external`\n * is legal on both — a webhook posts synchronously, a push subscription does not.\n *\n * Shared so the wiring-time assert below and the build-time architecture scan enforce ONE rule.\n */\nexport const ENDPOINT_KINDS_BY_API_KIND: Record<ApiKind, readonly EndpointKind[]> = {\n    rpc: ['rpc', 'external'],\n    pubsub: ['cloudtasks', 'cron', 'external'],\n};\n\n/**\n * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub, declare at\n * least one endpoint, and every endpoint must declare a kind this api kind can actually deliver.\n * (Return-type is Promise<void>, a compile-time contract — TS erases types at runtime so it cannot\n * be re-checked here.)\n * @throws Error if conventions are violated.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function assertPubSubConventions(apiClass: Function): void {\n    assertApiKind(apiClass, 'pubsub');\n    const apiName = apiClass.name || 'Unknown';\n    if (!isApiPath(apiClass)) {\n        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);\n    }\n    const endpoints = getEndpoints(apiClass) || {};\n    if (Object.keys(endpoints).length === 0) {\n        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);\n    }\n    const allowed = ENDPOINT_KINDS_BY_API_KIND.pubsub;\n    const kinds = getEndpointKinds(apiClass);\n    for (const methodName of Object.keys(endpoints)) {\n        const kind = kinds[methodName];\n        if (kind !== undefined && allowed.includes(kind)) continue;\n        throw new Error(\n            `@PubSub API ${apiName}.${methodName} declares @Endpoint(..., '${kind ?? 'missing'}') — a ` +\n            `@PubSub contract is delivered through a queue, so it must be one of: ${allowed.join(' | ')}.`,\n        );\n    }\n}\n\n/**\n * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if\n * present, else `${ApiClassName}-${methodName}`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function getQueueName(apiClass: Function, methodName: string): string {\n    const overrides: Record<string, string> =\n        Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};\n    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;\n}\n"]}
+{"version":3,"file":"api-kind.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/api-kind.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\nimport {\n    EndpointKind,\n    RPC,\n    CLOUDTASKS,\n    CRON,\n    EXTERNAL,\n    METADATA_KEYS,\n    getEndpoints,\n    getEndpointKinds,\n    isApiPath,\n} from './decorators';\n\n/**\n * API KIND — whether a contract is synchronous RPC or fire-and-forget over a queue — plus the\n * queue-naming rules that only a @PubSub contract has.\n *\n * Split out of `decorators.ts` purely for size (max-file-lines); the dependency runs ONE way,\n * api-kind -> decorators, so there is no cycle. Auth modes and endpoint shape stay in\n * `decorators.ts`; everything here is re-exported from the package barrel, so no consumer import\n * changes and there is no second spelling of anything.\n */\n\n// ============================================================\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n// ============================================================\n\n/**\n * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).\n * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)\n * schedules a Cloud Task that is later delivered to the SAME controller endpoint.\n */\nexport type ApiKind = 'rpc' | 'pubsub';\n\n/**\n * @Rpc() - marks an API class as synchronous request/response (the default kind).\n * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function Rpc(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'rpc' as ApiKind, target);\n    };\n}\n\n/**\n * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method\n * MUST return Promise<void> (a compile-time contract on the abstract API). The\n * enqueue client and the controller share this one class, exactly like RPC.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function PubSub(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'pubsub' as ApiKind, target);\n    };\n}\n\n/**\n * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default\n * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function Queue(name: string): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const overrides: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};\n        overrides[propertyKey as string] = name;\n        Reflect.defineMetadata(METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);\n    };\n}\n\n/**\n * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function getApiKind(apiClass: Function): ApiKind {\n    return (Reflect.getMetadata(METADATA_KEYS.API_KIND, apiClass) as ApiKind) ?? 'rpc';\n}\n\n/**\n * Assert the API class is of the expected kind (used by the clients: the RPC\n * client rejects a @PubSub api and vice-versa).\n * @throws Error if the kind doesn't match.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function assertApiKind(apiClass: Function, expected: ApiKind): void {\n    const actual = getApiKind(apiClass);\n    if (actual !== expected) {\n        const apiName = apiClass.name || 'Unknown';\n        throw new Error(\n            `API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +\n                `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`,\n        );\n    }\n}\n\n/**\n * Which {@link EndpointKind}s each {@link ApiKind} may declare. A @PubSub contract is delivered\n * asynchronously by definition, so `rpc` is meaningless on it; an @Rpc contract has no queue, so\n * `cloudtasks`/`cron` on it would name a queue/schedule nothing could ever deliver to. `external`\n * is legal on both — a webhook posts synchronously, a push subscription does not.\n *\n * Shared so the wiring-time assert below and the build-time architecture scan enforce ONE rule.\n */\nexport const ENDPOINT_KINDS_BY_API_KIND: Record<ApiKind, readonly EndpointKind[]> = {\n    rpc: [RPC, EXTERNAL],\n    pubsub: [CLOUDTASKS, CRON, EXTERNAL],\n};\n\n/**\n * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub, declare at\n * least one endpoint, and every endpoint must declare a kind this api kind can actually deliver.\n * (Return-type is Promise<void>, a compile-time contract — TS erases types at runtime so it cannot\n * be re-checked here.)\n * @throws Error if conventions are violated.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function assertPubSubConventions(apiClass: Function): void {\n    assertApiKind(apiClass, 'pubsub');\n    const apiName = apiClass.name || 'Unknown';\n    if (!isApiPath(apiClass)) {\n        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);\n    }\n    const endpoints = getEndpoints(apiClass) || {};\n    if (Object.keys(endpoints).length === 0) {\n        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);\n    }\n    const allowed = ENDPOINT_KINDS_BY_API_KIND.pubsub;\n    const kinds = getEndpointKinds(apiClass);\n    for (const methodName of Object.keys(endpoints)) {\n        const kind = kinds[methodName];\n        if (kind !== undefined && allowed.includes(kind)) continue;\n        throw new Error(\n            `@PubSub API ${apiName}.${methodName} declares @Endpoint(..., '${kind ?? 'missing'}') — a ` +\n                `@PubSub contract is delivered through a queue, so it must be one of: ${allowed.join(' | ')}.`,\n        );\n    }\n}\n\n/**\n * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if\n * present, else `${ApiClassName}-${methodName}`.\n */\n// webpieces-disable no-function-outside-class -- decorator factory / reflect-metadata reader; moved verbatim from decorators.ts for file size, same module-scope shape as its siblings there\nexport function getQueueName(apiClass: Function, methodName: string): string {\n    const overrides: Record<string, string> =\n        Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};\n    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;\n}\n"]}

package/src/http/decorators.d.ts

@@ -1,8 +1,13 @@
 import 'reflect-metadata';
 import { MaskSpec, MaskMode } from './LogFieldMask';
 import { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';
-import { EndpointOptions, ExternalEndpointOptions } from './HttpEndpointOptions';
+import { EndpointOperation, EndpointOptions, ExternalEndpointOptions } from './HttpEndpointOptions';
+import { HttpMethod } from './HttpContract';
 export type { EndpointOptions, ExternalEndpointOptions } from './HttpEndpointOptions';
+export type { EndpointOperation } from './HttpEndpointOptions';
+export { READ, WRITE_IDEMPOTENT, WRITE } from './HttpEndpointOptions';
+export type { HttpMethod } from './HttpContract';
+export { GET, POST } from './HttpContract';
 export { PathParam, QueryParam, getHttpParameterDeclarations } from './http-parameter-decorators';
 /**
  * Metadata keys for storing API routing information.
@@ -20,6 +25,10 @@ export declare const METADATA_KEYS: {
     QUEUE_OVERRIDE: string;
     /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */
     ENDPOINT_OPTIONS: string;
+    /** Per-method required HTTP method, parallel to ENDPOINTS. */
+    ENDPOINT_HTTP_METHOD: string;
+    /** Per-method required read/write semantics, parallel to ENDPOINTS. */
+    ENDPOINT_OPERATION: string;
     /** Per-method @Endpoint trigger kind (rpc | cloudtasks | cron | external), parallel to ENDPOINTS. */
     ENDPOINT_KIND: string;
     /** Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. */
@@ -35,99 +44,30 @@ export declare const METADATA_KEYS: {
     /** Per-method explicit path/query parameter declarations, keyed by parameter index. */
     HTTP_PARAMETERS: string;
 };
-/**
- * WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture
- * graph draws it, and which Terraform resource must exist for it to ever fire:
- *
- *  - `rpc`        — a caller in this repo (or a browser) calls it synchronously. A direct arrow.
- *  - `cloudtasks` — a producer ENQUEUES it; Cloud Tasks delivers it later. Drawn producer → queue →
- *                   consumer, one queue node per METHOD (see {@link Queue}). Producer and consumer
- *                   being the SAME service is legal and common — the queue decouples them.
- *  - `cron`       — a scheduler fires it on a clock. Nothing in-repo calls it; drawn hanging off a
- *                   clock symbol. Backed by a Cloud Scheduler job.
- *  - `external`   — a system OUTSIDE this repo drives it (a GCP Pub/Sub push subscription, a Twilio
- *                   or Gmail webhook). Drawn as an inbound dashed arrow from that system.
- *
- * Declared PER METHOD, because one api class routinely mixes them: an admin contract can have
- * caller-driven endpoints AND a nightly cron sweep. A class-level marker cannot express that, which
- * is exactly why the graph could not tell these apart before.
- */
-export type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';
-/**
- * Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing
- * `Record<methodName, path>` shape every consumer iterates stays unchanged.
- */
-/**
- * @ApiPath(basePath) - Class decorator that marks a class as an API definition
- * and sets the base path for all endpoints.
- *
- * Usage:
- * ```typescript
- * @ApiPath('/api/save')
- * abstract class SaveApi {
- *   @WpAuthJwt({ roles: ['admin'] })
- *   @Endpoint('/item', 'rpc')
- *   save(request: SaveRequest): Promise<SaveResponse> { ... }
- * }
- * ```
- */
+/** Nominal backing keeps raw string literals out of endpoint declarations. */
+declare enum EndpointKindValue {
+    RPC = "rpc",
+    CLOUDTASKS = "cloudtasks",
+    CRON = "cron",
+    EXTERNAL = "external"
+}
+/** Short, statically importable decorator arguments. */
+export declare const RPC = EndpointKindValue.RPC;
+export declare const CLOUDTASKS = EndpointKindValue.CLOUDTASKS;
+export declare const CRON = EndpointKindValue.CRON;
+export declare const EXTERNAL = EndpointKindValue.EXTERNAL;
+/** Runtime trigger/delivery owner used by validation, architecture, and infrastructure tooling. */
+export type EndpointKind = typeof RPC | typeof CLOUDTASKS | typeof CRON | typeof EXTERNAL;
+/** Class decorator that sets the shared base path for all endpoints. */
 export declare function ApiPath(basePath: string): ClassDecorator;
 /**
- * @Endpoint(path, kind, options?) - Method decorator that registers an HTTP endpoint at the given
- * path and declares WHAT TRIGGERS it. POST is the default; GET is explicit in `httpMethod`.
- *
- * Usage:
- * ```typescript
- * @Endpoint('/item', 'rpc')
- * save(request: SaveRequest): Promise<SaveResponse> { ... }
- *
- * // enqueued by a producer, delivered later by Cloud Tasks:
- * @Endpoint('/send', 'cloudtasks')
- * send(request: SendRequest): Promise<void> { ... }
- *
- * // fired by Cloud Scheduler on a clock, called by nobody in this repo:
- * @Endpoint('/nightly', 'cron')
- * nightly(request: NightlyRequest): Promise<void> { ... }
- *
- * // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):
- * @Endpoint('/hook', 'external', { formPost: true, calledBy: 'twilio' })
- * inbound(request: InboundRequest): Promise<InboundResponse> { ... }
- * ```
- *
- * `kind` is REQUIRED and deliberately positional: it makes every pre-existing single-argument
- * `@Endpoint('/x')` a COMPILE error rather than something a lint rule has to chase, so no endpoint
- * can slip into the runtime architecture graph with its trigger left to guesswork. See
- * {@link EndpointKind} for what each value draws and which Terraform resource backs it.
- *
- * `calledBy` is REQUIRED for `external` FOR EXACTLY THE SAME REASON, enforced by the overloads below:
- * the one box on the runtime graph whose whole job is to say who calls us from outside could only
- * restate OUR OWN contract name, because nothing in the source ever said who the caller was. This is
- * BREAKING for published consumers, intentionally — an existing `@Endpoint(p, 'external', {...})`
- * stops compiling until it names its caller. Migration is one property; see the migration note in
- * `external-caller.ts`. Non-`external` endpoints are completely unaffected.
- *
- * The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); kind,
- * options and caller ride PARALLEL ENDPOINT_KIND / ENDPOINT_OPTIONS / ENDPOINT_CALLER maps.
- */
-export declare function Endpoint(path: string, kind: 'external', options: ExternalEndpointOptions): MethodDecorator;
-export declare function Endpoint(path: string, kind: Exclude<EndpointKind, 'external'>, options?: EndpointOptions): MethodDecorator;
-/**
- * @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the
- * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an
- * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire
- * untouched — masking lives in the logging path only.
- *
- * ```typescript
- * @Endpoint('/account', 'rpc')
- * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })
- * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }
- * ```
- *
- * Matching is by field NAME at any depth (nested objects + array elements), so
- * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client
- * `[API-client-*]` and server `[API-server-*]` lines mask it. The spec is read ONCE at route-build
- * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.
+ * Registers `@Endpoint(POST, path, WRITE, RPC)`. Method, operation, and trigger are required enum
+ * values. Operation is independent of the HTTP verb. EXTERNAL additionally requires `calledBy`.
+ * Each classification rides a parallel metadata map while ENDPOINTS remains method-name -> path.
  */
+export declare function Endpoint(httpMethod: HttpMethod, path: string, operation: EndpointOperation, kind: typeof EXTERNAL, options: ExternalEndpointOptions): MethodDecorator;
+export declare function Endpoint(httpMethod: HttpMethod, path: string, operation: EndpointOperation, kind: Exclude<EndpointKind, typeof EXTERNAL>, options?: EndpointOptions): MethodDecorator;
+/** Declares request/response DTO field names that API logging must mask at any depth. */
 export declare function MaskLog(fields: Record<string, MaskMode>): MethodDecorator;
 /**
  * The @MaskLog spec for one method, or undefined if the method declared none (the common case — the
@@ -186,7 +126,7 @@ export declare function WpAuthSharedSecret(key: string): MethodDecorator;
  *
  * ```typescript
  * @WpAuthWebhook('sentry')
- * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })
+ * @Endpoint(POST, '/hook/sentry/issue', WRITE, EXTERNAL, { calledBy: 'sentry', rawBody: true })
  * abstract notify(request: SentryIssueHook): Promise<HookAck>;
  * ```
  *
@@ -208,56 +148,10 @@ export declare function WpAuthSharedSecret(key: string): MethodDecorator;
  */
 export declare function WpAuthWebhook(name: string): MethodDecorator;
 /**
- * @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`
- * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries
- * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other
- * companies' codebases (POS vendors, back-office platforms, ETL pipelines).
- *
- * ```typescript
- * @WpAuthApiKey('onetablet-partner', [
- *     { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },
- *     { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },
- * ])
- * @ApiPath('/management/v1')
- * abstract class ManagementApi { ... }
- * ```
- *
- * `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as
- * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,
- * and an api contract is level 0, so it never references a verifier directly.
- *
- * `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator
- * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing
- * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real
- * regime authenticates a PAIR — the key names a customer, a second header names which of that
- * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two
- * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects
- * would mean "either alone suffices", which is a load-bearing difference a single-credential shape
- * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are
- * presented in the published document.
- *
- * The list can never be EMPTY — a contract that declares a key regime and then names no credential
- * would generate a document with no security block, which is the exact silent failure this argument
- * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty
- * tuple, the same device for the same reason).
- *
- * WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other
- * end, so the framework BELIEVES the trusted context headers that caller forwarded (see
- * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal
- * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone
- * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits
- * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when
- * the hook independently derived the SAME value.
- *
- * WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a
- * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted
- * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole
- * inbound request instead, so the app owns which headers carry the credential and validates them as a
- * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no
- * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.
- *
- * FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and
- * `WebhookAuthCallback`.
+ * Declares a customer-held API-key regime and its non-empty ordered credential locations. The app's
+ * `ApiKeyHook` validates the whole request and supplies trusted context; the declaration only drives
+ * contract/spec metadata. Unlike shared-secret auth, partner callers cannot assert trusted context.
+ * Missing hooks fail closed with 401.
  */
 export declare function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator;
 /**
@@ -267,7 +161,7 @@ export declare function WpAuthApiKey(regime: string, credentials: ApiKeyCredenti
  *
  * ```typescript
  * @WpAuthLocalOnly()
- * @Endpoint('/logs', 'rpc')
+ * @Endpoint(POST, '/logs', WRITE, RPC)
  * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }
  * ```
  *
@@ -311,10 +205,14 @@ export declare function getEndpointKinds(apiClass: Function): Record<string, End
  * the required argument exists to remove.
  */
 export declare function getEndpointKind(apiClass: Function, methodName: string): EndpointKind | undefined;
+/** The required HTTP method for one endpoint. */
+export declare function getEndpointHttpMethod(apiClass: Function, methodName: string): HttpMethod;
 /**
  * Get the @Endpoint options for one method (empty object if the method had no options).
  */
 export declare function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions;
+/** Read one endpoint's required side-effect semantics. */
+export declare function getEndpointOperation(apiClass: Function, methodName: string): EndpointOperation;
 /**
  * Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}
  * overloads already make that a COMPILE error; this is the backstop for the ways TS is bypassed —

package/src/http/decorators.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MISSING_AUTH_DECORATOR_FIX = exports.METADATA_KEYS = exports.getHttpParameterDeclarations = exports.QueryParam = exports.PathParam = void 0;
+exports.MISSING_AUTH_DECORATOR_FIX = exports.EXTERNAL = exports.CRON = exports.CLOUDTASKS = exports.RPC = exports.METADATA_KEYS = exports.getHttpParameterDeclarations = exports.QueryParam = exports.PathParam = exports.POST = exports.GET = exports.WRITE = exports.WRITE_IDEMPOTENT = exports.READ = void 0;
 exports.ApiPath = ApiPath;
 exports.Endpoint = Endpoint;
 exports.MaskLog = MaskLog;
@@ -17,7 +17,9 @@ exports.getApiPath = getApiPath;
 exports.getEndpoints = getEndpoints;
 exports.getEndpointKinds = getEndpointKinds;
 exports.getEndpointKind = getEndpointKind;
+exports.getEndpointHttpMethod = getEndpointHttpMethod;
 exports.getEndpointOptions = getEndpointOptions;
+exports.getEndpointOperation = getEndpointOperation;
 exports.assertEveryExternalEndpointDeclaresCaller = assertEveryExternalEndpointDeclaresCaller;
 exports.isFormPost = isFormPost;
 exports.isRawBody = isRawBody;
@@ -32,7 +34,16 @@ const LogFieldMask_1 = require("./LogFieldMask");
 const external_caller_1 = require("./external-caller");
 // The TYPE layer these decorators attach — split out for file size only (see auth-mode.ts).
 const auth_mode_1 = require("./auth-mode");
+const HttpEndpointOptions_1 = require("./HttpEndpointOptions");
+const HttpContract_1 = require("./HttpContract");
 const http_parameter_decorators_1 = require("./http-parameter-decorators");
+var HttpEndpointOptions_2 = require("./HttpEndpointOptions");
+Object.defineProperty(exports, "READ", { enumerable: true, get: function () { return HttpEndpointOptions_2.READ; } });
+Object.defineProperty(exports, "WRITE_IDEMPOTENT", { enumerable: true, get: function () { return HttpEndpointOptions_2.WRITE_IDEMPOTENT; } });
+Object.defineProperty(exports, "WRITE", { enumerable: true, get: function () { return HttpEndpointOptions_2.WRITE; } });
+var HttpContract_2 = require("./HttpContract");
+Object.defineProperty(exports, "GET", { enumerable: true, get: function () { return HttpContract_2.GET; } });
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return HttpContract_2.POST; } });
 var http_parameter_decorators_2 = require("./http-parameter-decorators");
 Object.defineProperty(exports, "PathParam", { enumerable: true, get: function () { return http_parameter_decorators_2.PathParam; } });
 Object.defineProperty(exports, "QueryParam", { enumerable: true, get: function () { return http_parameter_decorators_2.QueryParam; } });
@@ -53,6 +64,10 @@ exports.METADATA_KEYS = {
     QUEUE_OVERRIDE: 'webpieces:queue-override',
     /** Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. */
     ENDPOINT_OPTIONS: 'webpieces:endpoint-options',
+    /** Per-method required HTTP method, parallel to ENDPOINTS. */
+    ENDPOINT_HTTP_METHOD: 'webpieces:endpoint-http-method',
+    /** Per-method required read/write semantics, parallel to ENDPOINTS. */
+    ENDPOINT_OPERATION: 'webpieces:endpoint-operation',
     /** Per-method @Endpoint trigger kind (rpc | cloudtasks | cron | external), parallel to ENDPOINTS. */
     ENDPOINT_KIND: 'webpieces:endpoint-kind',
     /** Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. */
@@ -68,24 +83,20 @@ exports.METADATA_KEYS = {
     /** Per-method explicit path/query parameter declarations, keyed by parameter index. */
     HTTP_PARAMETERS: http_parameter_decorators_1.HTTP_PARAMETERS_METADATA_KEY,
 };
-/**
- * Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing
- * `Record<methodName, path>` shape every consumer iterates stays unchanged.
- */
-/**
- * @ApiPath(basePath) - Class decorator that marks a class as an API definition
- * and sets the base path for all endpoints.
- *
- * Usage:
- * ```typescript
- * @ApiPath('/api/save')
- * abstract class SaveApi {
- *   @WpAuthJwt({ roles: ['admin'] })
- *   @Endpoint('/item', 'rpc')
- *   save(request: SaveRequest): Promise<SaveResponse> { ... }
- * }
- * ```
- */
+/** Nominal backing keeps raw string literals out of endpoint declarations. */
+var EndpointKindValue;
+(function (EndpointKindValue) {
+    EndpointKindValue["RPC"] = "rpc";
+    EndpointKindValue["CLOUDTASKS"] = "cloudtasks";
+    EndpointKindValue["CRON"] = "cron";
+    EndpointKindValue["EXTERNAL"] = "external";
+})(EndpointKindValue || (EndpointKindValue = {}));
+/** Short, statically importable decorator arguments. */
+exports.RPC = EndpointKindValue.RPC;
+exports.CLOUDTASKS = EndpointKindValue.CLOUDTASKS;
+exports.CRON = EndpointKindValue.CRON;
+exports.EXTERNAL = EndpointKindValue.EXTERNAL;
+/** Class decorator that sets the shared base path for all endpoints. */
 function ApiPath(basePath) {
     return (target) => {
         if (Reflect.hasMetadata('webpieces:ipc-api-id', target)) {
@@ -99,48 +110,53 @@ function ApiPath(basePath) {
     };
 }
 // webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function Endpoint(path, kind, options = {}) {
+function Endpoint(httpMethod, path, operation, kind, options = {}) {
+    validateEndpointClassification(httpMethod, operation, kind);
     // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
     return (target, propertyKey, _descriptor) => {
         const metadataTarget = typeof target === 'function' ? target : target.constructor;
-        const endpoints = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, metadataTarget) || {};
-        endpoints[propertyKey] = path;
-        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);
-        const kinds = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_KIND, metadataTarget) || {};
-        kinds[propertyKey] = kind;
-        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);
-        const opts = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) || {};
-        opts[propertyKey] = options;
-        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);
-        // ONLY for 'external', mirroring how a queue name is recorded only for the kinds that HAVE
-        // a queue: a caller on an rpc endpoint would be a fact about nothing.
-        const declared = options;
-        if (kind !== 'external' ||
-            typeof declared.calledBy !== 'string' ||
-            declared.calledBy === '')
-            return;
-        const callers = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) || {};
-        callers[propertyKey] = new external_caller_1.ExternalCaller(declared.callerKind ?? external_caller_1.DEFAULT_CALLER_KIND, declared.calledBy);
-        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);
+        recordEndpointMetadata(metadataTarget, propertyKey, httpMethod, path, operation, kind, options);
     };
 }
-/**
- * @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the
- * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an
- * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire
- * untouched — masking lives in the logging path only.
- *
- * ```typescript
- * @Endpoint('/account', 'rpc')
- * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })
- * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }
- * ```
- *
- * Matching is by field NAME at any depth (nested objects + array elements), so
- * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client
- * `[API-client-*]` and server `[API-server-*]` lines mask it. The spec is read ONCE at route-build
- * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.
- */
+// webpieces-disable no-function-outside-class -- runtime validation backs up nominal TS enums
+function validateEndpointClassification(httpMethod, operation, kind) {
+    if (!isHttpMethod(httpMethod)) {
+        throw new Error(`@Endpoint httpMethod must be GET or POST, received '${String(httpMethod)}'.`);
+    }
+    if (!isEndpointOperation(operation)) {
+        throw new Error(`@Endpoint operation must be READ, WRITE_IDEMPOTENT, or WRITE, received '${String(operation)}'.`);
+    }
+    if (!isEndpointKind(kind)) {
+        throw new Error(`@Endpoint trigger must be RPC, CLOUDTASKS, CRON, or EXTERNAL, received '${String(kind)}'.`);
+    }
+}
+// webpieces-disable no-function-outside-class -- one metadata write shared by the decorator overloads
+function recordEndpointMetadata(metadataTarget, propertyKey, httpMethod, path, operation, kind, options) {
+    const endpoints = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, metadataTarget) || {};
+    endpoints[propertyKey] = path;
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);
+    const methods = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_HTTP_METHOD, metadataTarget) || {};
+    methods[propertyKey] = httpMethod;
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_HTTP_METHOD, methods, metadataTarget);
+    const operations = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPERATION, metadataTarget) || {};
+    operations[propertyKey] = operation;
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_OPERATION, operations, metadataTarget);
+    const kinds = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_KIND, metadataTarget) || {};
+    kinds[propertyKey] = kind;
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);
+    const opts = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) || {};
+    opts[propertyKey] = options;
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);
+    const declared = options;
+    if (kind !== exports.EXTERNAL ||
+        typeof declared.calledBy !== 'string' ||
+        declared.calledBy === '')
+        return;
+    const callers = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) || {};
+    callers[propertyKey] = new external_caller_1.ExternalCaller(declared.callerKind ?? external_caller_1.DEFAULT_CALLER_KIND, declared.calledBy);
+    Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);
+}
+/** Declares request/response DTO field names that API logging must mask at any depth. */
 // webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
 function MaskLog(fields) {
     const spec = new LogFieldMask_1.MaskSpec(fields);
@@ -254,7 +270,7 @@ function WpAuthSharedSecret(key) {
  *
  * ```typescript
  * @WpAuthWebhook('sentry')
- * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })
+ * @Endpoint(POST, '/hook/sentry/issue', WRITE, EXTERNAL, { calledBy: 'sentry', rawBody: true })
  * abstract notify(request: SentryIssueHook): Promise<HookAck>;
  * ```
  *
@@ -279,56 +295,10 @@ function WpAuthWebhook(name) {
     return defineAuthMode({ kind: 'webhook', name });
 }
 /**
- * @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`
- * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries
- * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other
- * companies' codebases (POS vendors, back-office platforms, ETL pipelines).
- *
- * ```typescript
- * @WpAuthApiKey('onetablet-partner', [
- *     { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },
- *     { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },
- * ])
- * @ApiPath('/management/v1')
- * abstract class ManagementApi { ... }
- * ```
- *
- * `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as
- * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,
- * and an api contract is level 0, so it never references a verifier directly.
- *
- * `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator
- * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing
- * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real
- * regime authenticates a PAIR — the key names a customer, a second header names which of that
- * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two
- * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects
- * would mean "either alone suffices", which is a load-bearing difference a single-credential shape
- * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are
- * presented in the published document.
- *
- * The list can never be EMPTY — a contract that declares a key regime and then names no credential
- * would generate a document with no security block, which is the exact silent failure this argument
- * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty
- * tuple, the same device for the same reason).
- *
- * WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other
- * end, so the framework BELIEVES the trusted context headers that caller forwarded (see
- * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal
- * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone
- * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits
- * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when
- * the hook independently derived the SAME value.
- *
- * WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a
- * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted
- * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole
- * inbound request instead, so the app owns which headers carry the credential and validates them as a
- * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no
- * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.
- *
- * FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and
- * `WebhookAuthCallback`.
+ * Declares a customer-held API-key regime and its non-empty ordered credential locations. The app's
+ * `ApiKeyHook` validates the whole request and supplies trusted context; the declaration only drives
+ * contract/spec metadata. Unlike shared-secret auth, partner callers cannot assert trusted context.
+ * Missing hooks fail closed with 401.
  */
 // webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
 function WpAuthApiKey(regime, credentials) {
@@ -341,7 +311,7 @@ function WpAuthApiKey(regime, credentials) {
  *
  * ```typescript
  * @WpAuthLocalOnly()
- * @Endpoint('/logs', 'rpc')
+ * @Endpoint(POST, '/logs', WRITE, RPC)
  * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }
  * ```
  *
@@ -401,13 +371,56 @@ function getEndpointKinds(apiClass) {
 function getEndpointKind(apiClass, methodName) {
     return getEndpointKinds(apiClass)[methodName];
 }
+/** The required HTTP method for one endpoint. */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointKind
+function getEndpointHttpMethod(apiClass, methodName) {
+    const methods = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_HTTP_METHOD, apiClass) || {};
+    const method = methods[methodName];
+    if (!isHttpMethod(method)) {
+        throw new Error(`@Endpoint ${apiClass.name || 'Unknown'}.${methodName} must declare GET or POST.`);
+    }
+    return method;
+}
 /**
  * Get the @Endpoint options for one method (empty object if the method had no options).
  */
 // webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints
 function getEndpointOptions(apiClass, methodName) {
     const opts = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) || {};
-    return opts[methodName] ?? {};
+    const options = opts[methodName];
+    if (!options && getEndpoints(apiClass)?.[methodName] === undefined) {
+        // Preserve the historical helper behavior for a method that is not an endpoint at all.
+        return {};
+    }
+    return options ?? {};
+}
+/** Read one endpoint's required side-effect semantics. */
+// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointOptions
+function getEndpointOperation(apiClass, methodName) {
+    const operations = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINT_OPERATION, apiClass) || {};
+    const operation = operations[methodName];
+    if (!isEndpointOperation(operation)) {
+        throw new Error(`@Endpoint ${apiClass.name || 'Unknown'}.${methodName} must declare READ, ` +
+            'WRITE_IDEMPOTENT, or WRITE.');
+    }
+    return operation;
+}
+// webpieces-disable no-function-outside-class -- runtime backstop for JavaScript and `as any` callers; webpieces-disable no-any-unknown -- untrusted runtime value is narrowed to an endpoint operation
+function isEndpointOperation(value) {
+    return (value === HttpEndpointOptions_1.READ ||
+        value === HttpEndpointOptions_1.WRITE_IDEMPOTENT ||
+        value === HttpEndpointOptions_1.WRITE);
+}
+// webpieces-disable no-function-outside-class -- runtime backstop for JavaScript and `as any` callers; webpieces-disable no-any-unknown -- untrusted runtime value is narrowed to an HTTP method
+function isHttpMethod(value) {
+    return value === HttpContract_1.GET || value === HttpContract_1.POST;
+}
+// webpieces-disable no-function-outside-class -- runtime backstop for JavaScript and `as any` callers; webpieces-disable no-any-unknown -- untrusted runtime value is narrowed to an endpoint kind
+function isEndpointKind(value) {
+    return (value === exports.RPC ||
+        value === exports.CLOUDTASKS ||
+        value === exports.CRON ||
+        value === exports.EXTERNAL);
 }
 /**
  * Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}
@@ -423,7 +436,7 @@ function assertEveryExternalEndpointDeclaresCaller(apiClass) {
             (0, external_caller_1.getEndpointCaller)(apiClass, methodName) !== undefined)
             continue;
         throw new Error(`External endpoint '${methodName}' in ${apiClass.name || 'Unknown'} declares no caller. Say WHO ` +
-            `posts to it: @Endpoint(path, 'external', { calledBy: '<vendor>' }) — the runtime architecture ` +
+            `posts to it: @Endpoint(POST, path, WRITE, EXTERNAL, { calledBy: '<vendor>' }) — the runtime architecture ` +
             `graph cannot name an inbound caller it was never told about.`);
     }
 }