@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/types/http-schema.test-d.ts

@@ -0,0 +1,248 @@
+// tests/http-schema.types.test.ts
+import { test, describe, expectTypeOf } from "vitest";
+import type {
+  HttpParameters,
+  ExtractMethod,
+  ExtractPathParams,
+  ExtractQueryParams,
+  ExtractBodyParams,
+  HttpRequestFn,
+  HttpRequestOptions,
+} from "./http-schema.js"; // <-- adjust this import
+
+//
+// Sample schema (based on the doc comment)
+//
+type MySchema = [
+  {
+    readonly Route: "/users/:userId";
+    readonly Method: "GET";
+    readonly Parameters: HttpParameters<
+      readonly [readonly ["userId", string]],
+      { verbose?: boolean },
+      never
+    >;
+    readonly ReturnType: { id: string; name: string };
+  },
+  {
+    readonly Route: "/users/:userId/posts/:postId";
+    readonly Method: "GET";
+    readonly Parameters: HttpParameters<
+      readonly [readonly ["userId", string], readonly ["postId", string]],
+      never,
+      never
+    >;
+    readonly ReturnType: { id: string; title: string };
+  },
+  {
+    readonly Route: "/users";
+    readonly Method: "POST";
+    readonly Parameters: HttpParameters<
+      never,
+      never,
+      { name: string; email: string }
+    >;
+    readonly ReturnType: { id: string };
+  },
+  {
+    readonly Route: "/users/:userId";
+    readonly Method: "PATCH";
+    readonly Parameters: HttpParameters<
+      readonly [readonly ["userId", string]],
+      never,
+      { name?: string }
+    >;
+    readonly ReturnType: { id: string; name: string };
+  },
+];
+
+describe("Http schema type helpers", () => {
+  test("ExtractMethod returns correct methods for a route", () => {
+    type MethodForUser = ExtractMethod<MySchema, "/users/:userId">;
+
+    // There are two entries for "/users/:userId": GET + PATCH
+    expectTypeOf<MethodForUser>().toEqualTypeOf<"GET" | "PATCH">();
+  });
+
+  test("ExtractPathParams converts ordered tuples to a record", () => {
+    type UserPathParams = ExtractPathParams<MySchema, "/users/:userId">;
+    type PostPathParams = ExtractPathParams<
+      MySchema,
+      "/users/:userId/posts/:postId"
+    >;
+
+    // Path params for "/users/:userId"
+    expectTypeOf<UserPathParams>().toEqualTypeOf<
+      readonly [readonly ["userId", string]]
+    >();
+
+    // Path params for "/users/:userId/posts/:postId"
+    expectTypeOf<PostPathParams>().toEqualTypeOf<
+      readonly [readonly ["userId", string], readonly ["postId", string]]
+    >();
+  });
+
+  test("ExtractQueryParams returns the right query type", () => {
+    type UserQueryParams = ExtractQueryParams<MySchema, "/users/:userId">;
+    type PostsQueryParams = ExtractQueryParams<
+      MySchema,
+      "/users/:userId/posts/:postId"
+    >;
+
+    expectTypeOf<UserQueryParams>().toEqualTypeOf<{ verbose?: boolean }>();
+    expectTypeOf<PostsQueryParams>().toEqualTypeOf<never>(); // route has `never` query
+  });
+
+  test("ExtractBodyParams returns the right body type", () => {
+    type CreateUserBody = ExtractBodyParams<MySchema, "/users">;
+    type PatchUserBody = ExtractBodyParams<MySchema, "/users/:userId">;
+    type GetUserBody = ExtractBodyParams<
+      MySchema,
+      "/users/:userId/posts/:postId"
+    >;
+
+    expectTypeOf<CreateUserBody>().toEqualTypeOf<{
+      name: string;
+      email: string;
+    }>();
+
+    expectTypeOf<PatchUserBody>().toEqualTypeOf<{ name?: string }>();
+
+    // no body for this GET route
+    expectTypeOf<GetUserBody>().toEqualTypeOf<never>();
+  });
+});
+
+describe("HttpRequestFn", () => {
+  const request: HttpRequestFn<MySchema> = async (args) => {
+    // We don't care about runtime here; just satisfy the type.
+    // Narrow return type based on `args.route` (not required for the tests).
+    switch (args.route) {
+      case "/users/:userId":
+        return { id: "123", name: "John Doe" } as any;
+      case "/users/:userId/posts/:postId":
+        return { id: "1", title: "Post" } as any;
+      case "/users":
+        return { id: "123" } as any;
+      default:
+        throw new Error("Unknown route");
+    }
+  };
+
+  test("typed call for GET /users/:userId with path & query", async () => {
+    const user = await request({
+      method: "PATCH",
+      route: "/users/:userId",
+      path: { userId: "123" }, // Path is normalized to record
+      body: { name: "foo" },
+    });
+
+    // Both GET and PATCH return the same shape for this route.
+    expectTypeOf(user).toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  test("typed call for GET /users/:userId/posts/:postId", async () => {
+    const post = await request({
+      method: "GET",
+      route: "/users/:userId/posts/:postId",
+      path: { userId: "123", postId: "456" },
+    });
+
+    expectTypeOf(post).toEqualTypeOf<{ id: string; title: string }>();
+  });
+
+  test("typed call for POST /users with required body", async () => {
+    const created = await request({
+      method: "POST",
+      route: "/users",
+      body: { name: "Jane", email: "jane@example.com" },
+    });
+
+    expectTypeOf(created).toEqualTypeOf<{ id: string }>();
+  });
+
+  test("missing required body for POST /users should be an error", async () => {
+    // @ts-expect-error body is required for /users
+    await request({
+      route: "/users",
+    });
+
+    await request({
+      route: "/users",
+      // @ts-expect-error body is required (shape mismatch)
+      body: { wrong: "shape" },
+    });
+  });
+
+  test("path is required where schema has path params", async () => {
+    await request({
+      method: "GET",
+      route: "/users/:userId",
+      path: { userId: "123" },
+      query: { verbose: true },
+    });
+  });
+
+  test("query is optional when underlying type is optional", async () => {
+    await request({
+      method: "GET",
+      route: "/users/:userId",
+      path: { userId: "123" },
+      query: { verbose: false },
+    });
+
+    await request({
+      method: "GET",
+      route: "/users/:userId",
+      path: { userId: "123" },
+    });
+  });
+
+  test("default / loose mode when Schema is undefined", async () => {
+    const looseRequest: HttpRequestFn<undefined> = async (args) => {
+      return args as any;
+    };
+
+    // Any route string is allowed
+    await looseRequest({
+      method: "GET",
+      route: "/anything",
+      path: { foo: "bar" },
+      query: { x: 1 },
+      body: { whatever: true },
+    });
+  });
+});
+
+describe("HttpRequestOptions.routes OneOf", () => {
+  test("routes can have include", () => {
+    const opts: HttpRequestOptions = {
+      routes: { include: ["/users", "/posts"] },
+    };
+    expectTypeOf(opts.routes).toMatchTypeOf<
+      | { include?: string[] | undefined }
+      | { exclude?: string[] | undefined }
+      | undefined
+    >();
+  });
+
+  test("routes can have exclude", () => {
+    const opts: HttpRequestOptions = {
+      routes: { exclude: ["/health"] },
+    };
+    expectTypeOf(opts.routes).toMatchTypeOf<
+      | { include?: string[] | undefined }
+      | { exclude?: string[] | undefined }
+      | undefined
+    >();
+  });
+
+  test("routes cannot have both include and exclude", () => {
+    const bad: HttpRequestOptions = {
+      // @ts-expect-error OneOf should not allow both include and exclude
+      routes: { include: ["/users"], exclude: ["/posts"] },
+    };
+
+    void bad;
+  });
+});

package/src/sdk/types/http-schema.ts

@@ -0,0 +1,395 @@
+import type { OneOf } from "../../wit/type-utils.js";
+
+/**
+ * HTTP methods
+ */
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS";
+
+/**
+ * HTTP parameter types
+ */
+export type PathParams = Record<string, string | number>;
+export type OrderedPathParams = readonly (readonly [string, string | number])[];
+export type QueryParams = Record<
+  string,
+  string | number | boolean | (string | number | boolean)[] | undefined
+>;
+export type BodyParams = unknown;
+
+/**
+ * Container for different parameter types
+ */
+
+export type HttpParameters<
+  Path extends PathParams | OrderedPathParams | undefined =
+    | PathParams
+    | OrderedPathParams
+    | undefined,
+  Query extends QueryParams | undefined = QueryParams | undefined,
+  Body extends BodyParams | undefined = BodyParams | undefined,
+> = {
+  path: Path;
+  query: Query;
+  body: Body;
+};
+
+/**
+ * Generic HTTP schema entry.
+ *
+ * `Route` is the URL path template with parameter placeholders (e.g. `/users/:userId/posts/:postId`)
+ *
+ * `Method` specifies the HTTP method (GET, POST, etc.)
+ */
+
+export type HttpSchemaEntry<
+  R extends string = string,
+  M extends HttpMethod = HttpMethod,
+  P extends HttpParameters = HttpParameters,
+  T = unknown,
+> = {
+  readonly Route: R;
+  readonly Method: M;
+  readonly Parameters?: P | undefined;
+  readonly ReturnType: T;
+};
+
+export type HttpSchema = readonly HttpSchemaEntry[];
+
+export type ExtractRouteEntry<
+  S extends HttpSchema,
+  R extends S[number]["Route"],
+  M extends S[number]["Method"] | undefined = undefined,
+> = [M] extends [undefined]
+  ? Extract<S[number], { Route: R }>
+  : Extract<S[number], { Route: R; Method: M }>;
+
+/**
+ * Type helpers to extract specific parameter types
+ */
+export type ExtractMethod<
+  S extends HttpSchema,
+  R extends S[number]["Route"],
+> = ExtractRouteEntry<S, R>["Method"];
+
+export type ExtractPathParams<
+  S extends HttpSchema,
+  R extends S[number]["Route"],
+> =
+  ExtractRouteEntry<S, R>["Parameters"] extends HttpParameters<
+    infer Path,
+    any,
+    any
+  >
+    ? Path
+    : never;
+
+export type ExtractQueryParams<
+  S extends HttpSchema,
+  R extends S[number]["Route"],
+> =
+  ExtractRouteEntry<S, R>["Parameters"] extends HttpParameters<
+    any,
+    infer Query,
+    any
+  >
+    ? Query
+    : never;
+
+export type ExtractBodyParams<
+  S extends HttpSchema,
+  R extends S[number]["Route"],
+> =
+  ExtractRouteEntry<S, R>["Parameters"] extends HttpParameters<
+    any,
+    any,
+    infer Body
+  >
+    ? Body
+    : never;
+
+/**
+ * Helper to check if a parameter type is required (not undefined or optional)
+ */
+type IsRequired<T> = undefined extends T ? false : true;
+
+/**
+ * Helper to convert OrderedPathParams to a path params object
+ */
+type OrderedToRecord<T extends OrderedPathParams> = {
+  [K in T[number][0]]: Extract<T[number], readonly [K, any]>[1];
+};
+
+/**
+ * Helper to normalize path params (handles both ordered and record forms)
+
+*/
+
+type NormalizePathParams<P> = P extends OrderedPathParams
+  ? OrderedToRecord<P>
+  : P extends PathParams
+    ? P
+    : never;
+
+/**
+ * Build the params object shape based on what's defined in Parameters
+ */
+// type BuildParamsShape<P extends HttpParameters | undefined> =
+//   P extends HttpParameters
+//     ? (IsRequired<P["path"]> extends true
+//         ? { path: NormalizePathParams<P["path"]> }
+//         : { path?: NormalizePathParams<P["path"]> }) &
+//         (IsRequired<P["query"]> extends true
+//           ? { query: P["query"] }
+//           : { query?: P["query"] }) &
+//         (IsRequired<P["body"]> extends true
+//           ? { body: P["body"] }
+//           : { body?: P["body"] })
+//     : { path?: PathParams; query?: QueryParams; body?: BodyParams };
+//
+// type BuildParamsShape<P extends HttpParameters | undefined> =
+//   P extends HttpParameters
+//     ? (IsRequired<P["path"]> extends true
+//         ? { path: NormalizePathParams<Exclude<P["path"], undefined>> }
+//         : { path?: NormalizePathParams<Exclude<P["path"], undefined>> }) &
+//         (IsRequired<P["query"]> extends true
+//           ? { query: Exclude<P["query"], undefined> }
+//           : { query?: Exclude<P["query"], undefined> }) &
+//         (IsRequired<P["body"]> extends true
+//           ? { body: Exclude<P["body"], undefined> }
+//           : { body?: Exclude<P["body"], undefined> })
+//     : { path?: PathParams; query?: QueryParams; body?: BodyParams };
+//
+//
+// type BuildParamsShape<P extends HttpParameters | undefined> =
+//   P extends HttpParameters
+//     ? (IsRequired<P["path"]> extends true
+//         ? { path: NormalizePathParams<Exclude<P["path"], undefined>> }
+//         : { path?: NormalizePathParams<Exclude<P["path"], undefined>> }) &
+//         // 🔽 query: always optional, but type-safe when present
+//         (P["query"] extends undefined | never
+//           ? { query?: undefined } // effectively “no query”
+//           : { query?: Exclude<P["query"], undefined> }) &
+//         (IsRequired<P["body"]> extends true
+//           ? { body: Exclude<P["body"], undefined> }
+//           : { body?: Exclude<P["body"], undefined> })
+//     : { path?: PathParams; query?: QueryParams; body?: BodyParams };
+//
+//
+
+/**
+ * Generic HTTP request function, parameterized by an HttpSchema.
+ *
+ * When Schema is provided:
+ *   - `route` is restricted to the declared Route strings.
+ *   - `params` is typed from the matching entry's Parameters with proper path/query/body structure.
+ *   - return type is the entry's ReturnType.
+ *
+ * When Schema is `undefined`, it degrades to an untyped shape.
+ */
+
+export type HttpRequestFn<Schema extends HttpSchema | undefined> = <
+  S extends HttpSchema = Schema extends HttpSchema ? Schema : HttpSchema,
+  R extends S[number]["Route"] = S[number]["Route"],
+  M extends ExtractMethod<S, R> = ExtractMethod<S, R>,
+>(
+  args: Schema extends HttpSchema
+    ? {
+        route: R;
+        method: M;
+      } & BuildParamsShape<ExtractRouteEntry<S, R, M>["Parameters"]>
+    : {
+        route: string;
+        method: HttpMethod;
+        path?: PathParams;
+        query?: QueryParams;
+        body?: BodyParams;
+      },
+) => Promise<
+  Schema extends HttpSchema ? ExtractRouteEntry<S, R, M>["ReturnType"] : unknown
+>;
+
+// export type HttpRequestFn<Schema extends HttpSchema | undefined> = <
+//   S extends HttpSchema = Schema extends HttpSchema ? Schema : HttpSchema,
+//   R extends S[number]["Route"] = S[number]["Route"],
+// >(
+//   args: Schema extends HttpSchema
+//     ? {
+//         route: R;
+//       } & BuildParamsShape<ExtractRouteEntry<S, R>["Parameters"]>
+//     : {
+//         route: string;
+//         path?: PathParams;
+//         query?: QueryParams;
+//         body?: BodyParams;
+//       },
+// ) => Promise<
+//   Schema extends HttpSchema ? ExtractRouteEntry<S, R>["ReturnType"] : unknown
+// >;
+
+// type BuildParamsShape<P extends HttpParameters | undefined> =
+//   P extends HttpParameters
+//     ? // --- Path Parameters ---
+//       (IsRequired<P["path"]> extends true
+//         ? // If required, 'path' must be provided, using the non-nullable path type
+//           { path: NormalizePathParams<NonNullable<P["path"]>> }
+//         : // If optional, 'path' can be omitted or provided
+//           { path?: NormalizePathParams<NonNullable<P["path"]>> }) &
+//         // --- Query Parameters ---
+//         // Query is marked as always optional (`query?:`) unless it is explicitly `never` (or `undefined`)
+//         // The current block you settled on seems designed to handle this:
+//         (P["query"] extends undefined | never
+//           ? { query?: undefined } // Effectively hides 'query' if not present in schema
+//           : { query?: NonNullable<P["query"]> }) &
+//         // --- Body Parameters ---
+//         (IsRequired<P["body"]> extends true
+//           ? // If required, 'body' must be provided, using the non-nullable body type
+//             { body: NonNullable<P["body"]> }
+//           : // If optional, 'body' can be omitted or provided
+//             { body?: NonNullable<P["body"]> })
+//     : // Fallback for when no Parameters are specified
+//       { path?: PathParams; query?: QueryParams; body?: BodyParams };
+//
+// type BuildParamsShape<P extends HttpParameters | undefined> =
+//   P extends HttpParameters
+//     ? // --- Path Parameters ---
+//       (IsRequired<P["path"]> extends true
+//         ? { path: NormalizePathParams<NonNullable<P["path"]>> }
+//         : { path?: NormalizePathParams<NonNullable<P["path"]>> }) &
+//         // --- Query Parameters ---
+//         (P["query"] extends undefined | never
+//           ? {} // no `query` key when the schema says "no query"
+//           : { query?: NonNullable<P["query"]> }) &
+//         // --- Body Parameters ---
+//         (P["body"] extends undefined | never
+//           ? {} // 🔑 no `body` key when the schema says "no body"
+//           : IsRequired<P["body"]> extends true
+//             ? { body: NonNullable<P["body"]> }
+//             : { body?: NonNullable<P["body"]> })
+//     : // Fallback when no Parameters are specified
+//       { path?: PathParams; query?: QueryParams; body?: BodyParams };
+
+type BuildParamsShape<P extends HttpParameters | undefined> =
+  P extends HttpParameters
+    ? // --- Path Parameters ---
+      (P["path"] extends undefined | never
+        ? {} // no `path` key when the schema says "no path params"
+        : IsRequired<P["path"]> extends true
+          ? { path: NormalizePathParams<NonNullable<P["path"]>> }
+          : { path?: NormalizePathParams<NonNullable<P["path"]>> }) &
+        // --- Query Parameters ---
+        (P["query"] extends undefined | never
+          ? {} // no `query` key when the schema says "no query params"
+          : { query?: NonNullable<P["query"]> }) &
+        // --- Body Parameters ---
+        (P["body"] extends undefined | never
+          ? {} // no `body` key when the schema says "no body"
+          : IsRequired<P["body"]> extends true
+            ? { body: NonNullable<P["body"]> }
+            : { body?: NonNullable<P["body"]> })
+    : // Fallback for schema-less mode
+      { path?: PathParams; query?: QueryParams; body?: BodyParams };
+
+/**
+ * Options for HTTP request behavior (dedupe, retries, etc),
+ * symmetric with RpcRequestOptions.
+ */
+export type HttpRequestOptions = {
+  /** Deduplicate in-flight requests. */
+  dedupe?: boolean | undefined;
+  /** Routes to include or exclude from executing HTTP requests. */
+  routes?:
+    | OneOf<
+        | {
+            include?: string[] | undefined;
+          }
+        | {
+            exclude?: string[] | undefined;
+          }
+      >
+    | undefined;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number | undefined;
+  /** The max number of times to retry. */
+  retryCount?: number | undefined;
+  /** Unique identifier for the request. */
+  uid?: string | undefined;
+};
+
+/**
+ * Example usage:
+ *
+ * type MySchema = [
+ *   {
+ *     Route: "/users/:userId";
+ *     Method: "GET";
+ *     Parameters: HttpParameters<
+ *       readonly [readonly ["userId", string]],
+ *       { include?: string[] },
+ *       never
+ *     >;
+ *     ReturnType: { id: string; name: string };
+ *   },
+ *   {
+ *     Route: "/users/:userId/posts/:postId";
+ *     Method: "GET";
+ *     Parameters: HttpParameters<
+ *       readonly [
+ *         readonly ["userId", string],
+ *         readonly ["postId", string]
+ *       ],
+ *       never,
+ *       never
+ *     >;
+ *     ReturnType: { id: string; title: string };
+ *   },
+ *   {
+ *     Route: "/users";
+ *     Method: "POST";
+ *     Parameters: HttpParameters<never, never, { name: string; email: string }>;
+ *     ReturnType: { id: string };
+ *   },
+ *   {
+ *     Route: "/users/:userId";
+ *     Method: "PATCH";
+ *     Parameters: HttpParameters<
+ *       readonly [readonly ["userId", string]],
+ *       never,
+ *       { name?: string }
+ *     >;
+ *     ReturnType: { id: string; name: string };
+ *   },
+ * ];
+ *
+ * const request: HttpRequestFn<MySchema> = async (args) => {
+ *   // Implementation can access the method via schema
+ *   // Path params maintain their order for URL construction
+ * };
+ *
+ * // Usage with ordered path params converted to object for convenience:
+ * await request({
+ *   route: "/users/:userId",
+ *   path: { userId: "123" },
+ *   query: { include: ["posts"] }
+ * });
+ *
+ * await request({
+ *   route: "/users/:userId/posts/:postId",
+ *   path: { userId: "123", postId: "456" }
+ * });
+ *
+ * await request({
+ *   route: "/users",
+ *   body: { name: "John", email: "john@example.com" }
+ * });
+ *
+ * // Type helpers:
+ * type GetUserMethod = ExtractMethod<MySchema, "/users/:userId">; // "GET" | "PATCH"
+ * type CreateUserBody = ExtractBodyParams<MySchema, "/users">; // { name: string; email: string }
+ */