@ontrails/http 1.0.0-beta.16 → 1.0.0-beta.17

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ontrails/http
 
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
 ## 1.0.0-beta.16
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.17",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.15"
+    "@ontrails/core": "^1.0.0-beta.16"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

package/src/build.ts

@@ -1279,6 +1279,18 @@ const accumulateRoutes = (
  *
  * Returns `Result.err(ValidationError)` if two trails derive the same
  * (method, path) pair. Returns `Result.ok(routes)` on success.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpRoutes } from '@ontrails/http';
+ *
+ * const routes = deriveHttpRoutes(graph, { basePath: '/api' });
+ * if (routes.isErr()) throw routes.error;
+ *
+ * for (const route of routes.value) {
+ *   console.log(`${route.method} ${route.path}`);
+ * }
+ * ```
  */
 export const deriveHttpRoutes = (
   graph: Topo,

package/src/method.ts

@@ -12,13 +12,46 @@ export const httpMethodByIntent = {
   write: 'POST',
 } as const satisfies Record<Intent, HttpMethod>;
 
+/**
+ * Derive the HTTP method used for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpMethod } from '@ontrails/http';
+ *
+ * const method = deriveHttpMethod('read');
+ * // method === 'GET'
+ * ```
+ */
 export const deriveHttpMethod = (intent: Intent): HttpMethod =>
   (httpMethodByIntent as Partial<Record<string, HttpMethod>>)[intent] ?? 'POST';
 
+/**
+ * Derive the lowercase OpenAPI operation method for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpOperationMethod } from '@ontrails/http';
+ *
+ * const operationMethod = deriveHttpOperationMethod('destroy');
+ * // operationMethod === 'delete'
+ * ```
+ */
 export const deriveHttpOperationMethod = (
   intent: Intent
 ): HttpOperationMethod =>
   deriveHttpMethod(intent).toLowerCase() as HttpOperationMethod;
 
+/**
+ * Derive where request input should be read from for an HTTP method.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpInputSource } from '@ontrails/http';
+ *
+ * const source = deriveHttpInputSource('GET');
+ * // source === 'query'
+ * ```
+ */
 export const deriveHttpInputSource = (method: HttpMethod): InputSource =>
   method === 'GET' ? 'query' : 'body';

package/src/openapi.ts

@@ -331,6 +331,16 @@ const buildInfo = (
  * Iterates all trails, skipping signals and internal trails, and produces
  * paths, operations, parameters, and response schemas derived from
  * the trail contract.
+ *
+ * @example
+ * ```ts
+ * import { deriveOpenApiSpec } from '@ontrails/http';
+ *
+ * const spec = deriveOpenApiSpec(graph, {
+ *   basePath: '/api',
+ *   title: 'Demo API',
+ * });
+ * ```
  */
 export const deriveOpenApiSpec = (
   graph: Topo,