@krak-stack/registry 0.1.38 → 0.1.39

package/dist/lib/httpapi-adapter.d.ts

@@ -0,0 +1,73 @@
+import { Context, Effect, JsonSchema, Layer, Schema } from "effect";
+import type { Json } from "effect/Schema";
+import { HttpClient } from "effect/http";
+import { HttpApi, HttpApiGroup, OpenApi } from "effect/http-api";
+export type HttpApiMethod = "get" | "post" | "put" | "patch" | "delete";
+declare const HttpApiOperation: Schema.Struct<{
+    readonly operationId: Schema.optional<Schema.String>;
+    readonly summary: Schema.optional<Schema.String>;
+    readonly description: Schema.optional<Schema.String>;
+    readonly tags: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly parameters: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+        readonly required: Schema.optional<Schema.Boolean>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly schema: Schema.optional<Schema.Codec<Json, Json, never, never>>;
+    }>>>;
+    readonly requestBody: Schema.optional<Schema.Struct<{
+        readonly required: Schema.optional<Schema.Boolean>;
+        readonly content: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly schema: Schema.optional<Schema.Codec<Json, Json, never, never>>;
+        }>>>;
+    }>>;
+}>;
+export type HttpApiOperation = typeof HttpApiOperation.Type;
+export type HttpApiOperationEntry = {
+    readonly method: HttpApiMethod;
+    readonly path: string;
+    readonly operation: HttpApiOperation;
+};
+export type HttpApiOperationInputValues = Readonly<Record<string, unknown>>;
+export type HttpApiOperationInput = {
+    readonly body?: unknown;
+    readonly headers: HttpApiOperationInputValues;
+    readonly params: HttpApiOperationInputValues;
+    readonly query: HttpApiOperationInputValues;
+};
+export type HttpApiOperationDefinition = HttpApiOperationEntry & {
+    readonly name: string;
+    readonly groupIdentifier: string;
+    readonly endpointIdentifier: string;
+    readonly topLevel: boolean;
+    readonly inputSchema: Schema.Codec<Partial<HttpApiOperationInput>, Json>;
+    readonly inputJsonSchema: JsonSchema.JsonSchema;
+    readonly successSchema?: Schema.Codec<unknown, unknown>;
+    readonly readOnly: boolean;
+    readonly destructive: boolean;
+    readonly idempotent: boolean;
+};
+export type HttpApiAdapterConfig<Id extends string, Groups extends HttpApiGroup.Constraint> = {
+    readonly api: HttpApi.HttpApi<Id, Groups>;
+    readonly baseUrl: string;
+    readonly methods?: ReadonlyArray<HttpApiMethod>;
+    readonly include?: (operation: HttpApiOperationEntry) => boolean;
+    readonly encodeResult?: (result: unknown, operation: HttpApiOperationDefinition) => Effect.Effect<Json, Error>;
+};
+export type HttpApiAdapterExecuteOptions = {
+    readonly operation: HttpApiOperationDefinition;
+    readonly input: Partial<HttpApiOperationInput>;
+};
+export type HttpApiAdapterService = {
+    readonly info: ReturnType<typeof OpenApi.fromApi>["info"];
+    readonly operations: ReadonlyArray<HttpApiOperationDefinition>;
+    readonly execute: (options: HttpApiAdapterExecuteOptions) => Effect.Effect<unknown, Error>;
+    readonly encodeResult: (result: unknown, operation: HttpApiOperationDefinition) => Effect.Effect<Json, Error>;
+};
+export declare const encodeHttpApiOperationResult: (result: unknown) => Effect.Effect<string | number | boolean | Schema.JsonArray | Schema.JsonObject | null, Error, never>;
+declare const HttpApiAdapter_base: Context.ServiceClass<HttpApiAdapter, "@krak-stack/registry/HttpApiAdapter", HttpApiAdapterService>;
+export declare class HttpApiAdapter extends HttpApiAdapter_base {
+    static readonly make: <Id extends string, Groups extends HttpApiGroup.Constraint>(config: HttpApiAdapterConfig<Id, Groups>) => Effect.Effect<HttpApiAdapterService, Error, HttpClient.HttpClient | import("effect/http-api/HttpApiMiddleware").MiddlewareClient<import("effect/http-api/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>>;
+    static readonly layer: <Id extends string, Groups extends HttpApiGroup.Constraint>(config: HttpApiAdapterConfig<Id, Groups>) => Layer.Layer<HttpApiAdapter, Error, HttpClient.HttpClient | Exclude<import("effect/http-api/HttpApiMiddleware").MiddlewareClient<import("effect/http-api/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/Scope").Scope>>;
+}
+export {};

package/dist/lib/httpapi-adapter.js

@@ -0,0 +1,189 @@
+// ../../src/lib/httpapi-adapter.ts
+import {
+  Context,
+  Effect,
+  Layer,
+  Option,
+  Schema,
+  SchemaTransformation
+} from "effect";
+import { HttpClient } from "effect/http";
+import { HttpApi, HttpApiClient, OpenApi } from "effect/http-api";
+var HttpApiMethods = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete"
+];
+var HttpApiOperation = Schema.Struct({
+  operationId: Schema.optional(Schema.String),
+  summary: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String),
+  tags: Schema.optional(Schema.Array(Schema.String)),
+  parameters: Schema.optional(Schema.Array(Schema.Struct({
+    name: Schema.String,
+    in: Schema.Literals(["path", "query", "header", "cookie"]),
+    required: Schema.optional(Schema.Boolean),
+    description: Schema.optional(Schema.String),
+    schema: Schema.optional(Schema.Json)
+  }))),
+  requestBody: Schema.optional(Schema.Struct({
+    required: Schema.optional(Schema.Boolean),
+    content: Schema.optional(Schema.Record(Schema.String, Schema.Struct({
+      schema: Schema.optional(Schema.Json)
+    })))
+  }))
+}).annotate({ identifier: "HttpApiOperation" });
+var UndefinedFromNull = Schema.Null.pipe(Schema.decodeTo(Schema.Undefined, SchemaTransformation.transform({
+  decode: () => {
+    return;
+  },
+  encode: () => null
+})));
+var HttpApiOperationResultValue = Schema.suspend(() => Schema.Union([
+  Schema.Null,
+  UndefinedFromNull,
+  Schema.String,
+  Schema.Number,
+  Schema.Boolean,
+  Schema.DateFromString,
+  Schema.Uint8ArrayFromBase64,
+  Schema.Array(HttpApiOperationResultValue),
+  Schema.Record(Schema.String, HttpApiOperationResultValue)
+]));
+var HttpApiOperationResult = Schema.Union([
+  HttpApiOperationResultValue,
+  Schema.Undefined
+]).annotate({ identifier: "HttpApiOperationResult" });
+var encodeHttpApiOperationResult = Effect.fn("HttpApiAdapter.encodeOperationResult")((result) => Schema.encodeUnknownEffect(HttpApiOperationResult)(result).pipe(Effect.map((encoded) => encoded ?? null), Effect.mapError((cause) => new Error("HTTP API result is not serializable", { cause }))));
+var encodeOperationResult = Effect.fn("HttpApiAdapter.encodeResult")((result, operation) => operation.successSchema ? Schema.encodeUnknownEffect(operation.successSchema)(result).pipe(Effect.flatMap(encodeHttpApiOperationResult), Effect.mapError((cause) => new Error("HTTP API result does not match its success schema", {
+  cause
+}))) : encodeHttpApiOperationResult(result));
+var reflectedSchema = (schema) => Schema.make(schema.ast);
+var sanitizeHttpName = (name) => name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+var httpApiToolName = (entry) => (entry.operation.operationId || `${entry.method}_${entry.path.replace(/^\/api\//, "").replace(/[/:{}]/g, "_")}`).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").slice(0, 64);
+var makeCatalogue = (api, methods, include) => Effect.try({
+  try: () => {
+    if (!HttpApi.isHttpApi(api))
+      throw new Error("HttpApiAdapter requires a valid HttpApi");
+    const spec = OpenApi.fromApi(api);
+    const reflected = new Map;
+    HttpApi.reflect(api, {
+      onGroup: () => {
+        return;
+      },
+      onEndpoint: ({ endpoint, group, successes }) => {
+        const operationId = Context.getOrElse(endpoint.annotations, OpenApi.Identifier, () => group.topLevel ? endpoint.identifier : `${group.identifier}.${endpoint.identifier}`);
+        if (reflected.has(operationId))
+          throw new Error(`Duplicate HTTP API operation ID: ${operationId}`);
+        const fields = {};
+        if (endpoint.params)
+          fields.params = Schema.toType(reflectedSchema(endpoint.params));
+        if (endpoint.query)
+          fields.query = Schema.optionalKey(Schema.toType(reflectedSchema(endpoint.query)));
+        if (endpoint.headers)
+          fields.headers = Schema.optionalKey(Schema.toType(reflectedSchema(endpoint.headers)));
+        const payloads = Array.from(endpoint.payload.values()).flatMap(({ schemas }) => schemas.map(reflectedSchema));
+        if (payloads.length === 1 && payloads[0])
+          fields.body = payloads[0];
+        else if (payloads.length > 1)
+          fields.body = Schema.Union(payloads);
+        const input = Object.keys(fields).length === 0 ? Schema.Record(Schema.String, Schema.Never) : Schema.Struct(fields);
+        const inputSchema = Schema.make(Schema.toCodecJson(input).ast).annotate({
+          identifier: `${sanitizeHttpName(operationId)}ToolInput`
+        });
+        const successSchemas = Array.from(successes.values()).flat().map(reflectedSchema);
+        reflected.set(operationId, {
+          groupIdentifier: group.identifier,
+          endpointIdentifier: endpoint.identifier,
+          topLevel: group.topLevel,
+          inputSchema,
+          successSchema: successSchemas.length === 1 ? successSchemas[0] : successSchemas.length > 1 ? Schema.Union(successSchemas) : undefined
+        });
+      }
+    });
+    const names = new Set;
+    const operations = [];
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+      for (const method of methods) {
+        const decoded = Schema.decodeUnknownOption(HttpApiOperation)(pathItem[method]);
+        if (Option.isNone(decoded))
+          continue;
+        const entry = { method, path, operation: decoded.value };
+        if (include && !include(entry))
+          continue;
+        const metadata = entry.operation.operationId ? reflected.get(entry.operation.operationId) : undefined;
+        if (!metadata)
+          throw new Error(`Missing endpoint schema for ${entry.operation.operationId}`);
+        const name = httpApiToolName(entry);
+        if (!name || names.has(name))
+          throw new Error(`Duplicate or empty HTTP API tool name: ${name}`);
+        names.add(name);
+        const document = Schema.toJsonSchemaDocument(metadata.inputSchema.annotate({ identifier: undefined }));
+        operations.push({
+          ...entry,
+          ...metadata,
+          name,
+          inputJsonSchema: {
+            ...document.schema,
+            $defs: document.definitions
+          },
+          readOnly: method === "get",
+          destructive: method === "delete",
+          idempotent: method === "get" || method === "put" || method === "delete"
+        });
+      }
+    }
+    return { info: spec.info, operations };
+  },
+  catch: (cause) => new Error("Failed to build HTTP API adapter catalogue", { cause })
+});
+var GeneratedOperation = Schema.declare((value) => value instanceof Function).annotate({ identifier: "GeneratedOperation" });
+var GeneratedOperationEffect = Schema.declare((value) => Effect.isEffect(value)).annotate({ identifier: "GeneratedOperationEffect" });
+var executeGeneratedOperation = Effect.fn("HttpApiAdapter.executeGeneratedOperation")(function* (client, { operation, input }) {
+  const group = operation.topLevel ? client : Object.entries(Object(client)).find(([name]) => name === operation.groupIdentifier)?.[1];
+  const candidate = Object.entries(Object(group)).find(([name]) => name === operation.endpointIdentifier)?.[1];
+  const endpoint = Schema.decodeUnknownOption(GeneratedOperation)(candidate);
+  if (Option.isNone(endpoint))
+    return yield* Effect.fail(new Error(`No generated API client operation for ${operation.operation.operationId}`));
+  const result = Schema.decodeUnknownOption(GeneratedOperationEffect)(endpoint.value({
+    headers: input.headers ?? {},
+    params: input.params ?? {},
+    query: input.query ?? {},
+    payload: input.body
+  }));
+  if (Option.isNone(result))
+    return yield* Effect.fail(new Error(`Generated API client operation ${operation.operation.operationId} is invalid`));
+  return yield* result.value;
+});
+
+class HttpApiAdapter extends Context.Service()("@krak-stack/registry/HttpApiAdapter") {
+  static make = Effect.fn("HttpApiAdapter.make")(function* (config) {
+    const catalogue = yield* makeCatalogue(config.api, config.methods ?? HttpApiMethods, config.include);
+    const httpClient = yield* HttpClient.HttpClient;
+    const client = yield* HttpApiClient.makeWith(config.api, {
+      baseUrl: config.baseUrl,
+      httpClient
+    });
+    return HttpApiAdapter.of({
+      ...catalogue,
+      encodeResult: config.encodeResult ?? encodeOperationResult,
+      execute: Effect.fn("HttpApiAdapter.execute")(function* (options) {
+        const operation = catalogue.operations.find((entry) => entry.method === options.operation.method && entry.path === options.operation.path && entry.operation.operationId === options.operation.operation.operationId);
+        if (!operation) {
+          return yield* Effect.fail(new Error("Operation is not in this HTTP API adapter catalogue"));
+        }
+        return yield* executeGeneratedOperation(client, {
+          operation,
+          input: options.input
+        });
+      })
+    });
+  });
+  static layer = (config) => Layer.effect(this, this.make(config));
+}
+export {
+  HttpApiAdapter,
+  encodeHttpApiOperationResult
+};

package/dist/lib/httpapi-cli.d.ts

@@ -1,25 +1,7 @@
-import { Cause, Context, Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect";
+import { Effect } from "effect";
 import { Command } from "effect/cli";
-import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
-import { ApiClient, type ApiClientService } from "./httpapi-client.js";
-import { HttpApiSpec, type HttpApiOperationEntry } from "./httpapi-helpers.js";
-declare const HttpApiCli_base: Context.ServiceClass<HttpApiCli, "HttpApiCli", {
+import { HttpApiAdapter } from "./httpapi-adapter.js";
+export declare const makeHttpApiCli: () => Effect.Effect<{
     command: Command.Command<string, {}, {}, unknown, never>;
     run: (args: ReadonlyArray<string>) => Effect.Effect<void, unknown, Command.Environment>;
-}> & {
-    readonly make: () => Effect.Effect<{
-        command: Command.Command<string, {}, {}, unknown, never>;
-        run: (args: ReadonlyArray<string>) => Effect.Effect<void, unknown, Command.Environment>;
-    }, Error, ApiClient | HttpApiSpec>;
-};
-export declare class HttpApiCli extends HttpApiCli_base {
-    static readonly layer: Layer.Layer<HttpApiCli, Error, ApiClient | HttpApiSpec>;
-}
-export declare const toHttpApiCliName: (value: string) => string;
-export declare const printHttpApiCliResult: (response: unknown, operation: HttpApiOperationEntry, client: ApiClientService) => Effect.Effect<void, unknown, never>;
-export declare const makeHttpApiCliCommand: () => Effect.Effect<Command.Command<string, {}, {}, unknown, never>, Error, ApiClient | HttpApiSpec>;
-export declare const httpApiCliEnvironmentLayer: (args: ReadonlyArray<string>) => Layer.Layer<ChildProcessSpawner | FileSystem.FileSystem | Path.Path | Stdio.Stdio | Terminal.Terminal, never, never>;
-export declare const httpApiCli: (args?: string[]) => Effect.Effect<void, unknown, HttpApiCli | Command.Environment>;
-export declare const formatHttpApiCliCause: (cause: Cause.Cause<unknown>) => string;
-export declare const runHttpApiCli: <E>(layer: Layer.Layer<HttpApiCli, E>, args?: string[]) => void;
-export {};
+}, Error, HttpApiAdapter>;