@modelprofile.com/flexharness 10.16.0 → 10.17.0

package/ts_typedrequest/interfaces.ts

@@ -0,0 +1,124 @@
+// The public types come from the package itself, not from plugins.ts, so the declarations of this
+// subpath never reach the optional peer @api.global/typedopenapi.
+import type {
+  IFlexCatalogRunContext,
+  IFlexCatalogType,
+  IFlexToolCatalog,
+  TFlexCatalogCallDecision,
+} from '@modelprofile.com/flexharness';
+
+/** A JSON Schema of the surface, plain JSON; its `$ref`s name `#/$defs/<type>` of the surface's types. */
+export type TFlexTypedRequestSchema = Record<string, unknown>;
+
+/** Where to read a typedrequest API's contracts, and what of them the catalog takes. */
+export interface IFlexTypedRequestSurfaceOptions {
+  /** The `tsconfig.json` of the project that holds the contracts. */
+  tsconfig: string;
+  /** The contract files, or a glob of several: `ts_interfaces/requests/*.ts`. */
+  contracts: string;
+  /** The names of the exports that are contracts (default `/^IReq_/`). */
+  contractNamePattern?: RegExp;
+  /**
+   * Request properties the binding fills from the run instead of the model, such as the caller's
+   * identity or a CSRF token: left out of every request's schema and declaration.
+   */
+  omit?: readonly string[];
+  /**
+   * The namespace of a contract's method. Default: the base name of the file that declares it
+   * (`vouchers` for `requests/vouchers.ts`, the folder's name for an `index.ts`).
+   */
+  area?(contract: { name: string; method: string; file: string }): string;
+}
+
+/** One typed method of a surface: how the catalog shows it and validates its calls. */
+export interface IFlexTypedRequestMethod {
+  /** The typed method the router answers: `getVoucher`. */
+  method: string;
+  /** The catalog path the model calls: `vouchers.getVoucher`. */
+  path: string;
+  /** The first sentence of the contract's JSDoc, or the method. */
+  summary: string;
+  /** The contract's JSDoc, its tags included. */
+  description?: string;
+  /** Set by a `@deprecated` tag on the contract. */
+  deprecated?: boolean;
+  /** The request's schema, without the omitted properties. */
+  inputSchema: TFlexTypedRequestSchema;
+  /** The response's schema. */
+  outputSchema: TFlexTypedRequestSchema;
+  /** `function getVoucher(params: …): Promise<…>;` as the contract writes it, after its JSDoc. */
+  declaration: string;
+}
+
+/**
+ * A typedrequest API as the catalog takes it, read from its TypeScript sources by
+ * `describeTypedRequests()`. Plain JSON, so a build step can write it and a server read it.
+ */
+export interface IFlexTypedRequestSurface {
+  /** The typed methods, by path. */
+  methods: IFlexTypedRequestMethod[];
+  /**
+   * The named types, by name: each with its JSON Schema where requests and responses refer to it,
+   * its TypeScript declaration where declarations name it, or both. A generic is declared once
+   * (`IPage`) and its instances have schemas (`IPage_IVoucher`).
+   */
+  types: IFlexCatalogType[];
+  /** The request properties left out of every request, which the binding fills. */
+  omit: string[];
+}
+
+/**
+ * A router that answers typed requests in process, such as a `TypedRouter` of
+ * `@api.global/typedrequest`.
+ */
+export interface IFlexTypedRequestRouter {
+  routeAndAddResponse(
+    request: IFlexTypedRequestEnvelope,
+    options?: {
+      trustedLocalData?: Record<string, unknown>;
+      trustedAbortSignal?: AbortSignal;
+    },
+  ): Promise<IFlexTypedRequestEnvelope | null>;
+}
+
+/** A typed request as the router takes it and answers it. */
+export interface IFlexTypedRequestEnvelope {
+  method: string;
+  request: object;
+  response: object;
+  correlation?: { id: string; phase: 'request' | 'response' };
+  error?: { text: string; data: any };
+}
+
+/** How a catalog answers a surface's methods. */
+export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
+  /** The router that answers the methods, in process. */
+  router: IFlexTypedRequestRouter;
+  /**
+   * The request properties the surface leaves out, from the run: `{ identity }` of the user the
+   * session acts for. They are merged over the model's parameters.
+   */
+  request?(
+    method: IFlexTypedRequestMethod,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
+  /** Server-owned data the handlers read as `localData`, as a transport would hand it. */
+  localData?(
+    method: IFlexTypedRequestMethod,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
+  /** The methods the model may use. Default: every method that is not deprecated. */
+  include?(method: IFlexTypedRequestMethod): boolean;
+  /** Other names of methods, by typed method: `{ getVoucher: ['Beleg abrufen'] }`. */
+  aliases?: Readonly<Record<string, readonly string[]>>;
+  /** The words the API's users say for its own words; see `IFlexToolCatalog.vocabulary`. */
+  vocabulary?: IFlexToolCatalog['vocabulary'];
+  /** Decides each validated call before it runs; see `IFlexCatalogMethod.onCall`. */
+  onCall?(
+    method: IFlexTypedRequestMethod,
+    params: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): TFlexCatalogCallDecision | PromiseLike<TFlexCatalogCallDecision>;
+  /** Receives the calls `onCall` proposed; see `IFlexToolCatalog.onProposals`. */
+  onProposals?: IFlexToolCatalog<TScope>['onProposals'];
+}

package/ts_typedrequest/plugins.ts

@@ -0,0 +1,15 @@
+// node native scope
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+
+export { crypto, path };
+
+// @modelprofile.com scope
+import { FlexHarnessValidationError, FlexToolCatalog } from '@modelprofile.com/flexharness';
+
+export { FlexHarnessValidationError, FlexToolCatalog };
+
+// @api.global scope: @api.global/typedopenapi is an optional peer, loaded only to describe a surface
+
+/** Loads @api.global/typedopenapi, which reads the contracts from their TypeScript sources. */
+export const importTypedOpenApi = async () => await import('@api.global/typedopenapi');

package/ts_typedrequest/readme.md

@@ -0,0 +1,66 @@
+A FlexHarness tool catalog from a typedrequest API: the model reads the API's contracts as their authors wrote them, and its calls run through the API's own router in process.
+
+```sh
+pnpm add @modelprofile.com/flexharness @api.global/typedrequest
+pnpm add -D @api.global/typedopenapi   # where the surface is described
+```
+
+```typescript
+import { catalogFromTypedRequests, describeTypedRequests } from '@modelprofile.com/flexharness/typedrequest';
+
+// At build time, or at startup where the sources are at hand: plain JSON.
+const surface = await describeTypedRequests({
+  tsconfig: './tsconfig.json',
+  contracts: './ts_interfaces/requests/*.ts',
+  omit: ['identity'],
+});
+
+// At run time: the catalog of a tool provider.
+const catalog = catalogFromTypedRequests<IAppScope>(surface, {
+  router: server.typedrouter,
+  request: (method, context) => ({ identity: identityOf(context.provider.scope) }),
+  onCall: (method) => (method.method.startsWith('get') || method.method.startsWith('list') ? 'run' : 'propose'),
+});
+```
+
+`describeTypedRequests()` reads the contracts with `@api.global/typedopenapi`, an optional peer it loads only when it runs:
+
+- Each typed method becomes a method of the path `<area>.<method>`; the area is the base name of the file that declares the contract (`vouchers` for `requests/vouchers.ts`, the folder's name for an `index.ts`), or what `area` returns. A name that is no identifier is mapped as `FlexToolCatalog.identifierOf()` maps it (`export` becomes `export_`).
+- Its declaration is the contract as written: `function getVoucher(params: { voucherId: string }): Promise<{ voucher: IVoucher }>;` after the contract's JSDoc with its tags, the request property's JSDoc as `@param params`, the response property's as `@returns`. `params` is optional where the request requires nothing.
+- Its `inputSchema` and `outputSchema` are the request's and response's JSON Schema; `execute` validates every call against the request's.
+- `omit` names request properties the binding fills from the run, such as the caller's identity or a CSRF token: they leave every request's schema and declaration, so the model can neither see nor send them.
+- The named types the requests and responses reach become the catalog's types, each with its JSON Schema, its declaration from the sources, or both: a generic is declared once (`IPage<T>`) and its instances have schemas (`IPage_IVoucher`). A method's result types are declared only as deep as `toolCatalog.outputTypeDepth` asks, as for any declaration.
+
+The surface is plain JSON, so a build step can write it next to the server and the server read it at startup without TypeScript or `@api.global/typedopenapi`. A 330-method API is described in about 8 seconds.
+
+`catalogFromTypedRequests(surface, options)` returns an `IFlexToolCatalog`:
+
+- `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters and what `request` returns for the omitted properties, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
+- A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
+- `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
+- A surface that omits properties needs `request`; an alias for a method the surface lacks is refused.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.