kizunajs 2.0.0-beta.15 → 2.0.0-beta.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +1 -1
  2. package/dist/{adapter-BcwpTn32.mjs → adapter-Bz9TLpbr.mjs} +119 -48
  3. package/dist/{adapter-Do23zdY1.d.mts → adapter-C9fbHfjn.d.mts} +79 -49
  4. package/dist/{adapter-B75LpzDv.cjs → adapter-CrrbTr4O.cjs} +142 -65
  5. package/dist/{adapter-O2unN9bH.d.cts → adapter-oar_-jZV.d.cts} +79 -49
  6. package/dist/adapter.cjs +7 -7
  7. package/dist/adapter.d.cts +3 -3
  8. package/dist/adapter.d.mts +3 -3
  9. package/dist/adapter.mjs +5 -5
  10. package/dist/{error-response-D2bAIpNd.d.mts → error-response-NoOGdh8H.d.mts} +13 -17
  11. package/dist/{error-response-Da3XXloD.d.cts → error-response-YbkRMKno.d.cts} +13 -17
  12. package/dist/generator.cjs +3 -3
  13. package/dist/generator.d.cts +6 -3
  14. package/dist/generator.d.mts +6 -3
  15. package/dist/generator.mjs +3 -3
  16. package/dist/index.cjs +42 -12
  17. package/dist/index.d.cts +132 -75
  18. package/dist/index.d.mts +132 -75
  19. package/dist/index.mjs +42 -13
  20. package/dist/jobs-entry.cjs +2 -2
  21. package/dist/jobs-entry.d.cts +1 -1
  22. package/dist/jobs-entry.d.mts +1 -1
  23. package/dist/jobs-entry.mjs +2 -2
  24. package/dist/{plugin-D_WJ2GBf.cjs → plugin-Dw-yCjTY.cjs} +4 -6
  25. package/dist/{plugin-server-C9i5kuJN.mjs → plugin-server-BztlE1fz.mjs} +9 -6
  26. package/dist/{plugin-server-CIC64cSM.cjs → plugin-server-kUsK7thV.cjs} +9 -6
  27. package/dist/{plugin-CFpv8XTz.mjs → plugin-xxCxibmu.mjs} +3 -5
  28. package/dist/plugin.cjs +1 -1
  29. package/dist/plugin.d.cts +2 -2
  30. package/dist/plugin.d.mts +2 -2
  31. package/dist/plugin.mjs +1 -1
  32. package/dist/{protected-resource-metadata-03dcSdwj.d.cts → protected-resource-metadata-B9hMFQ9N.d.cts} +1 -1
  33. package/dist/{protected-resource-metadata-By4Un6Oc.d.mts → protected-resource-metadata-CfBVsqIk.d.mts} +1 -1
  34. package/dist/schemas.cjs +1 -1
  35. package/dist/schemas.d.cts +2 -2
  36. package/dist/schemas.d.mts +2 -2
  37. package/dist/schemas.mjs +1 -1
  38. package/package.json +1 -1
  39. package/src/adapter.ts +3 -3
  40. package/src/api-definition.ts +11 -15
  41. package/src/api.ts +2 -2
  42. package/src/configured.ts +9 -6
  43. package/src/define-config.ts +41 -17
  44. package/src/generator.ts +7 -4
  45. package/src/group-routes.ts +106 -0
  46. package/src/groups.ts +140 -0
  47. package/src/handler-pipeline.ts +14 -7
  48. package/src/index.ts +4 -2
  49. package/src/kizuna.ts +37 -31
  50. package/src/routes.ts +80 -32
  51. package/src/types.ts +13 -17
  52. package/src/tags.ts +0 -67
  53. /package/dist/{schemas-7y2XV1if.cjs → schemas-DNPVDvkd.cjs} +0 -0
  54. /package/dist/{schemas-_W2cLAVl.mjs → schemas-HW2FDsvz.mjs} +0 -0
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  A spec-driven framework for building fully typed REST APIs in TypeScript, where your route declarations produce the validation, the documentation, the clients, and the AI tools.
6
6
 
7
- [![npm](https://img.shields.io/npm/v/kizunajs/beta?color=blue&label=npm)](https://www.npmjs.com/package/kizunajs/v/2.0.0-beta.15)
7
+ [![npm](https://img.shields.io/npm/v/kizunajs/beta?color=blue&label=npm)](https://www.npmjs.com/package/kizunajs/v/2.0.0-beta.17)
8
8
  ![license](https://img.shields.io/badge/license-MIT-blue)
9
9
 
10
10
  [Documentation](https://kizunajs.com)
@@ -1,33 +1,8 @@
1
- import { g as ROUTES_TAG, n as PLUGIN_SERVERS_META_KEY, o as pluginRouteTree, p as HANDLER, t as PLUGIN_ROUTES_META_KEY } from "./plugin-CFpv8XTz.mjs";
1
+ import { g as ROUTES_GROUP, n as PLUGIN_SERVERS_META_KEY, o as pluginRouteTree, p as HANDLER, t as PLUGIN_ROUTES_META_KEY } from "./plugin-xxCxibmu.mjs";
2
2
  import { E as resolveBaseType, T as readObjectShape, c as isBinarySchema, o as findCoercedSchemaPath, p as isVoidSchema, t as ProblemDetailsSchema } from "./error-response-CNQaKVYd.mjs";
3
- import { F as routeStreams, G as isZodSchema, H as isJsonMediaType, J as resolveResponseBody, L as streamContentType, M as assertValidStreams, N as encodeStreamBody, S as dueSchedules, U as isStreamResponse, W as isSuccessStatus, X as resolveResponseContentType, Y as resolveResponseCache, Z as resolveResponseEtag, _ as jobAt, c as cacheHeaders, ct as allowedMethodsForPath, dt as isRouteDefinition, ft as validateRequest, h as isCompiledJob, j as EVENT_STREAM_MEDIA_TYPE, k as deriveToolNames, lt as flattenRoutes, m as flattenJobs, pt as resolveCoercionPlans, st as parsePath, u as deprecationHeaders, ut as formatValidationError, y as toJobResponse, z as streamSchemas } from "./plugin-server-C9i5kuJN.mjs";
4
- import { l as authenticationChallenge, p as resolveSecurityRequirements } from "./schemas-_W2cLAVl.mjs";
3
+ import { F as routeStreams, G as isZodSchema, H as isJsonMediaType, J as resolveResponseBody, L as streamContentType, M as assertValidStreams, N as encodeStreamBody, S as dueSchedules, U as isStreamResponse, W as isSuccessStatus, X as resolveResponseContentType, Y as resolveResponseCache, Z as resolveResponseEtag, _ as jobAt, c as cacheHeaders, ct as allowedMethodsForPath, dt as isRouteDefinition, ft as validateRequest, h as isCompiledJob, j as EVENT_STREAM_MEDIA_TYPE, k as deriveToolNames, lt as flattenRoutes, m as flattenJobs, pt as resolveCoercionPlans, st as parsePath, u as deprecationHeaders, ut as formatValidationError, y as toJobResponse, z as streamSchemas } from "./plugin-server-BztlE1fz.mjs";
4
+ import { l as authenticationChallenge, p as resolveSecurityRequirements } from "./schemas-HW2FDsvz.mjs";
5
5
  import { z } from "zod";
6
- //#region src/tags.ts
7
- const isTagSet = (value) => typeof value === "object" && value !== null && "__brand" in value && value.__brand === "TagSet";
8
- /**
9
- * Define a set of tags. A tag value may be a full {@link TagOptions} object or a
10
- * string, which is shorthand for `{ title }`. Pass the result to `defineConfig`
11
- * under `tags`.
12
- *
13
- * @example
14
- * const tags = k.tags({
15
- * orders: {
16
- * title: 'Orders',
17
- * description: 'Create and manage orders',
18
- * },
19
- * health: 'Health',
20
- * });
21
- */
22
- const createTags = (tags) => {
23
- const normalized = {};
24
- for (const [key, value] of Object.entries(tags)) normalized[key] = typeof value === "string" ? { title: value } : value;
25
- return {
26
- __brand: "TagSet",
27
- tags: normalized
28
- };
29
- };
30
- //#endregion
31
6
  //#region src/tool-definitions.ts
32
7
  /**
33
8
  * What a route says about publishing itself, or `undefined` when it says
@@ -360,28 +335,124 @@ const validateRoutes = (routes, prefix) => {
360
335
  } else if (value && typeof value === "object") validateRoutes(value, fullKey);
361
336
  }
362
337
  };
363
- function tagRoutes(first, second, third) {
364
- if (isTagSet(first)) {
365
- if (third !== void 0) {
366
- const result = third;
367
- result[ROUTES_TAG] = second;
368
- validateRoutes(result);
369
- return result;
338
+ const isDeclared = (value) => typeof value === "object" && value !== null && ROUTES_GROUP in value;
339
+ const groupOf = (value) => isDeclared(value) ? value[ROUTES_GROUP] : void 0;
340
+ /**
341
+ * Throw on a grouped tree nested inside another. It belongs in `defineConfig`'s
342
+ * list.
343
+ */
344
+ const assertNoGroupInside = (routes, prefix) => {
345
+ for (const [key, value] of Object.entries(routes)) {
346
+ if (isRouteDefinition(value) || !value || typeof value !== "object") continue;
347
+ const fullKey = prefix ? `${prefix}.${key}` : key;
348
+ const group = groupOf(value);
349
+ if (group !== void 0 && group !== "") throw new Error(`"${fullKey}" was declared into the group ${group}, so its key comes from there. List it in defineConfig's \`routes\` instead of nesting it.`);
350
+ assertNoGroupInside(value, fullKey);
351
+ }
352
+ };
353
+ function groupRoutes(first, second) {
354
+ const routes = typeof first === "string" ? second : first;
355
+ assertNoGroupInside(routes);
356
+ routes[ROUTES_GROUP] = typeof first === "string" ? first : "";
357
+ validateRoutes(routes);
358
+ return routes;
359
+ }
360
+ /**
361
+ * Merge `source` into `target`, throwing when both hold the same key.
362
+ */
363
+ const mergeRoutes = (target, source, path) => {
364
+ for (const [key, value] of Object.entries(source)) {
365
+ const fullKey = path === "" ? key : `${path}.${key}`;
366
+ const existing = target[key];
367
+ if (existing === void 0) {
368
+ target[key] = value;
369
+ continue;
370
370
  }
371
- const result = second;
372
- validateRoutes(result);
373
- return result;
371
+ if (isRouteDefinition(existing) || isRouteDefinition(value)) throw new Error(`Two routes claim the key "${fullKey}". Rename one, or declare it into another group.`);
372
+ const merged = { ...existing };
373
+ mergeRoutes(merged, value, fullKey);
374
+ target[key] = merged;
374
375
  }
375
- if (typeof first === "string") {
376
- const result = second;
377
- result[ROUTES_TAG] = first;
378
- validateRoutes(result);
379
- return result;
376
+ };
377
+ /**
378
+ * The route tree a list of declared trees makes, each at its group's path.
379
+ */
380
+ const assembleRoutes = (declared) => {
381
+ const root = {};
382
+ for (const entry of declared) {
383
+ const routes = isDeclared(entry) ? entry : groupRoutes(entry);
384
+ const group = routes[ROUTES_GROUP];
385
+ let node = root;
386
+ let path = "";
387
+ for (const segment of group === "" ? [] : group.split(".")) {
388
+ path = path === "" ? segment : `${path}.${segment}`;
389
+ const existing = node[segment];
390
+ if (isRouteDefinition(existing)) throw new Error(`The route "${path}" sits where the group ${group} needs its key. Rename the route, or the group.`);
391
+ if (existing === void 0) node[segment] = {};
392
+ node = node[segment];
393
+ }
394
+ if (group !== "") node[ROUTES_GROUP] = group;
395
+ mergeRoutes(node, routes, path);
380
396
  }
381
- const result = first;
382
- validateRoutes(result);
383
- return result;
384
- }
397
+ return root;
398
+ };
399
+ //#endregion
400
+ //#region src/groups.ts
401
+ const isGroupSet = (value) => typeof value === "object" && value !== null && "__brand" in value && value.__brand === "GroupSet";
402
+ const collect = (declared, ancestors, into) => {
403
+ for (const [key, value] of Object.entries(declared)) {
404
+ if (key.includes(".")) throw new Error(`The group "${key}" has a dot in its key. Nest it under \`groups\` instead.`);
405
+ const options = typeof value === "string" ? { title: value } : value;
406
+ const parent = ancestors[ancestors.length - 1];
407
+ const path = parent === void 0 ? key : `${parent}.${key}`;
408
+ const lineage = [...ancestors, path];
409
+ into.set(path, {
410
+ path,
411
+ title: options.title,
412
+ ...options.description === void 0 ? {} : { description: options.description },
413
+ ...options.externalDocs === void 0 ? {} : { externalDocs: options.externalDocs },
414
+ lineage
415
+ });
416
+ if (options.groups) collect(options.groups, lineage, into);
417
+ }
418
+ };
419
+ /**
420
+ * Throw on two siblings with one title.
421
+ */
422
+ const assertUniqueTitles = (groups) => {
423
+ const owners = /* @__PURE__ */ new Map();
424
+ for (const group of groups.values()) {
425
+ const sibling = `${group.lineage[group.lineage.length - 2] ?? ""}\u0000${group.title}`;
426
+ const owner = owners.get(sibling);
427
+ if (owner !== void 0) throw new Error(`The groups "${owner}" and "${group.path}" share the title "${group.title}". Give each group its own title.`);
428
+ owners.set(sibling, group.path);
429
+ }
430
+ };
431
+ /**
432
+ * Declare the groups routes are filed under. A string is shorthand for
433
+ * `{ title }`.
434
+ *
435
+ * @example
436
+ * const groups = k.groups({
437
+ * workspace: {
438
+ * title: 'Workspace',
439
+ * groups: {
440
+ * members: 'Members',
441
+ * },
442
+ * },
443
+ * health: 'Health',
444
+ * });
445
+ */
446
+ const createGroups = (declared) => {
447
+ const groups = /* @__PURE__ */ new Map();
448
+ collect(declared, [], groups);
449
+ assertUniqueTitles(groups);
450
+ return {
451
+ __brand: "GroupSet",
452
+ declared,
453
+ groups
454
+ };
455
+ };
385
456
  //#endregion
386
457
  //#region src/permissions.ts
387
458
  const isPermissions = (value) => typeof value === "object" && value !== null && "__brand" in value && value.__brand === "Permissions";
@@ -2194,4 +2265,4 @@ const headersToObject = (headers) => {
2194
2265
  return result;
2195
2266
  };
2196
2267
  //#endregion
2197
- export { dispatchSucceeded as $, renderJsonResult as A, sortFlattenedRoutes as B, headersToObject as C, jobRunnerFrom as D, jobRoutes as E, isRawResponse as F, defineJobTransport as G, requiresDenial as H, rawResponse as I, jobFnAt as J, JobInputError as K, assertNoPathCollisions as L, runHandler as M, runRoute as N, parseBodyText as O, warnUnsupportedJobOptions as P, dispatchDueJobs as Q, routeClaims as R, guardDenyFor as S, jobRouter as T, withPermissions as U, insufficientScope as V, JobDispatchError as W, DispatchFailedSchema as X, ResponseError as Y, DispatchResultSchema as Z, defineAdapter as _, selectToolRoutes as _t, HANDLER_ARG_KEYS as a, getStatusText as at, extractCredential as b, createTags as bt, ROUTER_META as c, isPermissions as ct, SCHEMES_META as d, tagRoutes as dt, dueJobs as et, adapterContextOf as f, expandStreamTools as ft, contractOf as g, describeTool as gt, boundJobKeys as h, buildToolInputSchema as ht, GUARD_SCHEMA_META as i, STATUS_TITLES as it, routerFromRoutes as j, parseFetchBody as k, RUN_ROUTE_KEY as l, isRoles as lt, bearerChallenge as m, buildToolDefinitions as mt, DISPATCH_ROUTE_KEY as n, problemDetails as nt, JOBS_META as o, createPermissions as ot, assembleApi as p, toolEvents as pt, createJobRunner as q, GUARDS_META as r, problemFromBody as rt, REQUEST_CONTEXT_META as s, createRoles as st, API_META as t, failedJobs as tt, ResponseValidationError as u, permissionNames as ut, dispatchHandler as v, toolOptionsOf as vt, isGuardDenial as w, getHeaderValue as x, isTagSet as xt, dispatchRoute as y, toolRefusal as yt, matchRoute as z };
2268
+ export { dispatchSucceeded as $, renderJsonResult as A, sortFlattenedRoutes as B, headersToObject as C, jobRunnerFrom as D, jobRoutes as E, isRawResponse as F, defineJobTransport as G, requiresDenial as H, rawResponse as I, jobFnAt as J, JobInputError as K, assertNoPathCollisions as L, runHandler as M, runRoute as N, parseBodyText as O, warnUnsupportedJobOptions as P, dispatchDueJobs as Q, routeClaims as R, guardDenyFor as S, toolRefusal as St, jobRouter as T, withPermissions as U, insufficientScope as V, JobDispatchError as W, DispatchFailedSchema as X, ResponseError as Y, DispatchResultSchema as Z, defineAdapter as _, buildToolDefinitions as _t, HANDLER_ARG_KEYS as a, getStatusText as at, extractCredential as b, selectToolRoutes as bt, ROUTER_META as c, isPermissions as ct, SCHEMES_META as d, createGroups as dt, dueJobs as et, adapterContextOf as f, isGroupSet as ft, contractOf as g, toolEvents as gt, boundJobKeys as h, expandStreamTools as ht, GUARD_SCHEMA_META as i, STATUS_TITLES as it, routerFromRoutes as j, parseFetchBody as k, RUN_ROUTE_KEY as l, isRoles as lt, bearerChallenge as m, groupRoutes as mt, DISPATCH_ROUTE_KEY as n, problemDetails as nt, JOBS_META as o, createPermissions as ot, assembleApi as p, assembleRoutes as pt, createJobRunner as q, GUARDS_META as r, problemFromBody as rt, REQUEST_CONTEXT_META as s, createRoles as st, API_META as t, failedJobs as tt, ResponseValidationError as u, permissionNames as ut, dispatchHandler as v, buildToolInputSchema as vt, isGuardDenial as w, getHeaderValue as x, toolOptionsOf as xt, dispatchRoute as y, describeTool as yt, matchRoute as z };
@@ -1,4 +1,4 @@
1
- import { A as AutoResponsesBrand, D as AUTO_RESPONSES_BRAND, E as AUTO_GUARD_WRITTEN_BRAND, F as HANDLER, I as HANDLER_CONTEXT_BRAND, J as RouteHiddenToolCheck, K as RouteDefinition, L as HandlerContextBrand, O as AuthoredRouteDefinition, P as GuardStatus, U as ResponseDefinition, V as RequiredPermissions, W as ResponseHeaders, X as RouteToolOptions, Y as RoutePath, Z as Routes, a as OAuthFlows, at as ProblemDetails, b as RoleNamesOf, et as StreamDefinition, j as CachePolicy, m as GrantNamesOf, ot as StripProblemEnvelope, p as CatalogOf, q as RouteHandlerFunction, r as ContextOf, s as SecurityScheme, t as ProblemDetailsSchema, tt as StreamResponseDefinition, x as Roles, z as Method } from "./error-response-D2bAIpNd.mjs";
1
+ import { A as AutoResponsesBrand, D as AUTO_RESPONSES_BRAND, E as AUTO_GUARD_WRITTEN_BRAND, F as HANDLER, I as HANDLER_CONTEXT_BRAND, J as RouteHiddenToolCheck, K as RouteDefinition, L as HandlerContextBrand, O as AuthoredRouteDefinition, P as GuardStatus, U as ResponseDefinition, V as RequiredPermissions, W as ResponseHeaders, X as RouteToolOptions, Y as RoutePath, Z as Routes, a as OAuthFlows, at as ProblemDetails, b as RoleNamesOf, et as StreamDefinition, j as CachePolicy, m as GrantNamesOf, ot as StripProblemEnvelope, p as CatalogOf, q as RouteHandlerFunction, r as ContextOf, s as SecurityScheme, t as ProblemDetailsSchema, tt as StreamResponseDefinition, x as Roles, z as Method } from "./error-response-NoOGdh8H.mjs";
2
2
  import { z } from "zod";
3
3
 
4
4
  //#region src/identity.d.ts
@@ -832,9 +832,15 @@ declare const isRouteDefinition: (value: unknown) => value is RouteDefinition;
832
832
  interface FlattenedRoute {
833
833
  routeKey: string;
834
834
  route: RouteDefinition;
835
- routeTags: string[];
835
+ /**
836
+ * The route's groups, as dotted paths, its own first.
837
+ */
838
+ routeGroups: string[];
836
839
  }
837
- declare const flattenRoutes: (routes: Routes, prefix?: string, inheritedTags?: string[]) => FlattenedRoute[];
840
+ /**
841
+ * Flatten a tree of routes, each with its groups.
842
+ */
843
+ declare const flattenRoutes: (routes: Routes, prefix?: string, inheritedGroup?: string) => FlattenedRoute[];
838
844
  interface RawInputs {
839
845
  params: unknown;
840
846
  query: unknown;
@@ -916,59 +922,85 @@ interface RawResponse {
916
922
  declare const rawResponse: (response?: unknown) => RawResponse;
917
923
  declare const isRawResponse: (value: unknown) => value is RawResponse;
918
924
  //#endregion
919
- //#region src/tags.d.ts
920
- interface TagOptions {
925
+ //#region src/groups.d.ts
926
+ interface GroupOptions {
921
927
  /**
922
- * The tag name, used as the OpenAPI tag and shown in rendered API docs.
928
+ * The group's name in the docs. Unique among its siblings.
923
929
  */
924
930
  title: string;
925
931
  /**
926
- * Optional description shown alongside the tag in the OpenAPI spec.
932
+ * Shown beside the group in the OpenAPI document.
927
933
  */
928
934
  description?: string;
929
935
  /**
930
- * Optional external documentation for the tag.
936
+ * External documentation for the group.
931
937
  */
932
938
  externalDocs?: {
933
939
  url: string;
934
940
  description?: string;
935
941
  };
942
+ /**
943
+ * The groups nested under this one.
944
+ */
945
+ groups?: Record<string, GroupOptions | string>;
946
+ }
947
+ /**
948
+ * A declared group, with its place in the tree.
949
+ */
950
+ interface ResolvedGroup {
951
+ /**
952
+ * Its dotted path, `'workspace.members'`.
953
+ */
954
+ readonly path: string;
955
+ readonly title: string;
956
+ readonly description?: string;
957
+ readonly externalDocs?: GroupOptions['externalDocs'];
958
+ /**
959
+ * Dotted paths from the top group down to this one.
960
+ */
961
+ readonly lineage: readonly string[];
936
962
  }
937
963
  /**
938
- * A set of OpenAPI tags created with `k.tags`. Named in `defineConfig` under `tags`,
939
- * where routes reference each tag by its key.
964
+ * The groups from `k.groups`.
940
965
  */
941
- interface TagSet<T extends Record<string, TagOptions> = Record<string, TagOptions>> {
942
- readonly __brand: 'TagSet';
943
- readonly tags: T;
966
+ interface GroupSet<Declared extends Record<string, GroupOptions | string> = Record<string, GroupOptions | string>> {
967
+ readonly __brand: 'GroupSet';
968
+ /**
969
+ * The tree as written, for its type.
970
+ */
971
+ readonly declared: Declared;
972
+ /**
973
+ * Every group by dotted path, parents first.
974
+ */
975
+ readonly groups: ReadonlyMap<string, ResolvedGroup>;
944
976
  }
945
977
  /**
946
- * The union of tag keys declared in a {@link TagSet}, e.g. `'health' | 'users'`.
978
+ * Every dotted path a `k.groups` input declares.
979
+ */
980
+ type GroupPaths<Declared> = { [Key in Extract<keyof Declared, string>]: Key | (Declared[Key] extends {
981
+ groups: infer Nested;
982
+ } ? `${Key}.${GroupPaths<Nested>}` : never) }[Extract<keyof Declared, string>];
983
+ /**
984
+ * The dotted group paths a {@link GroupSet} declares.
947
985
  */
948
- type TagKeysOf<Set extends TagSet> = Set extends TagSet<infer T> ? Extract<keyof T, string> : never;
949
- declare const isTagSet: (value: unknown) => value is TagSet;
986
+ type GroupPathsOf<Set extends GroupSet> = Set extends GroupSet<infer Declared> ? GroupPaths<Declared> : never;
987
+ declare const isGroupSet: (value: unknown) => value is GroupSet;
950
988
  /**
951
- * Define a set of tags. A tag value may be a full {@link TagOptions} object or a
952
- * string, which is shorthand for `{ title }`. Pass the result to `defineConfig`
953
- * under `tags`.
989
+ * Declare the groups routes are filed under. A string is shorthand for
990
+ * `{ title }`.
954
991
  *
955
992
  * @example
956
- * const tags = k.tags({
957
- * orders: {
958
- * title: 'Orders',
959
- * description: 'Create and manage orders',
993
+ * const groups = k.groups({
994
+ * workspace: {
995
+ * title: 'Workspace',
996
+ * groups: {
997
+ * members: 'Members',
998
+ * },
960
999
  * },
961
1000
  * health: 'Health',
962
1001
  * });
963
1002
  */
964
- declare const createTags: <const T extends Record<string, TagOptions | string>>(tags: T) => TagSet<NormalizeTags<T>>;
965
- /**
966
- * Normalize a `k.tags` input, where each value is {@link TagOptions}
967
- * or a title string, into a uniform `Record<string, TagOptions>`.
968
- */
969
- type NormalizeTags<T extends Record<string, TagOptions | string>> = { [Key in keyof T]: T[Key] extends string ? {
970
- title: T[Key];
971
- } : T[Key] extends TagOptions ? T[Key] : never };
1003
+ declare const createGroups: <const Declared extends Record<string, GroupOptions | string>>(declared: Declared) => GroupSet<Declared>;
972
1004
  //#endregion
973
1005
  //#region src/request-context.d.ts
974
1006
  /**
@@ -1600,11 +1632,11 @@ declare const isCompiledJob: (value: unknown) => value is CompiledJob;
1600
1632
  //#endregion
1601
1633
  //#region src/api-definition.d.ts
1602
1634
  /**
1603
- * A kizuna API definition: its routes plus tags, identities, and validation
1635
+ * A kizuna API definition: its routes plus groups, identities, and validation
1604
1636
  * settings. Produced by `defineConfig` and consumed by the server adapters,
1605
1637
  * fetch client, OpenAPI generator, and SDK generators.
1606
1638
  */
1607
- interface ApiDefinition<Routes_ extends Routes = Routes, Tags extends Record<string, TagOptions> = Record<string, TagOptions>, Codes extends string = string, Schemes extends Record<string, SecurityScheme> = Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema> = Record<string, RequestContextSchema>, Plugins extends ApiPlugins = ApiPlugins, Jobs_ extends Jobs = Jobs, GuardSchema extends z.ZodType | undefined = z.ZodType | undefined> {
1639
+ interface ApiDefinition<Routes_ extends Routes = Routes, Groups extends Record<string, GroupOptions | string> = Record<string, GroupOptions | string>, Codes extends string = string, Schemes extends Record<string, SecurityScheme> = Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema> = Record<string, RequestContextSchema>, Plugins extends ApiPlugins = ApiPlugins, Jobs_ extends Jobs = Jobs, GuardSchema extends z.ZodType | undefined = z.ZodType | undefined> {
1608
1640
  /**
1609
1641
  * The API's route groups.
1610
1642
  */
@@ -1630,10 +1662,9 @@ interface ApiDefinition<Routes_ extends Routes = Routes, Tags extends Record<str
1630
1662
  */
1631
1663
  jobsConfig?: JobsConfig;
1632
1664
  /**
1633
- * The tag set declared with `k.tags`. Routes reference its keys; the
1634
- * OpenAPI generator resolves each key to its title and description.
1665
+ * The groups declared with `k.groups`.
1635
1666
  */
1636
- tags?: TagSet<Tags>;
1667
+ groups?: GroupSet<Groups>;
1637
1668
  /**
1638
1669
  * The identities named in `defineConfig`. A route's `auth` names them,
1639
1670
  * `defineConfig` writes each route's `security` from it, and the
@@ -1769,7 +1800,7 @@ declare const apiEntries: (module: Record<string, unknown>) => [string, ApiEntry
1769
1800
  * // src/kizuna.types.ts, generated
1770
1801
  * export interface Config {
1771
1802
  * adapter: ReturnType<typeof expressAdapter>;
1772
- * tags: typeof tags;
1803
+ * groups: typeof groups;
1773
1804
  * auth: { identities: { user: typeof user } };
1774
1805
  * jobs: typeof jobs;
1775
1806
  * }
@@ -1777,7 +1808,7 @@ declare const apiEntries: (module: Record<string, unknown>) => [string, ApiEntry
1777
1808
  */
1778
1809
  interface KizunaConfigShape {
1779
1810
  adapter?: unknown;
1780
- tags?: unknown;
1811
+ groups?: unknown;
1781
1812
  auth?: {
1782
1813
  identities?: unknown;
1783
1814
  guardSchema?: unknown;
@@ -1814,9 +1845,12 @@ interface JobFnOf<Definition extends AuthoredJobDefinition> {
1814
1845
  type JobsOfTree<Tree> = { [Key in keyof Tree]: Tree[Key] extends {
1815
1846
  definition: infer Definition extends AuthoredJobDefinition;
1816
1847
  } ? JobFnOf<Definition> : JobsOfTree<Tree[Key]> };
1817
- type ConfiguredTags<Config> = Config extends {
1818
- tags: TagSet<infer Tags extends Record<string, TagOptions>>;
1819
- } ? Tags : Record<string, never>;
1848
+ /**
1849
+ * The groups a config declares, or none.
1850
+ */
1851
+ type ConfiguredGroups<Config> = Config extends {
1852
+ groups: GroupSet<infer Groups extends Record<string, GroupOptions | string>>;
1853
+ } ? Groups : {};
1820
1854
  type ConfiguredCodes<Config> = Config extends {
1821
1855
  validation: {
1822
1856
  issueCodes: infer Codes extends string;
@@ -2216,14 +2250,10 @@ declare const createApiReference: () => {
2216
2250
  //#endregion
2217
2251
  //#region src/routes.d.ts
2218
2252
  /**
2219
- * Define a group of routes under a tag. Pass the tag set declared with
2220
- * `k.tags` for completion on the group tag and route-level `tags`; the
2221
- * tag is stamped onto every route in the group.
2253
+ * Validate a tree of routes and stamp its group's path, `''` for none.
2222
2254
  */
2223
- declare function tagRoutes<const T extends Routes<TagKeysOf<Set>>, Set extends TagSet>(tags: Set, tag: TagKeysOf<Set>, routes: T & PathParamsCheck<T>): T;
2224
- declare function tagRoutes<const T extends Routes<TagKeysOf<Set>>, Set extends TagSet>(tags: Set, routes: T & PathParamsCheck<T>): T;
2225
- declare function tagRoutes<const T extends Routes>(tag: string, routes: T & PathParamsCheck<T>): T;
2226
- declare function tagRoutes<const T extends Routes>(routes: T & PathParamsCheck<T>): T;
2255
+ declare function groupRoutes<const T extends Routes>(routes: T & PathParamsCheck<T>): T;
2256
+ declare function groupRoutes<const T extends Routes>(group: string, routes: T & PathParamsCheck<T>): T;
2227
2257
  //#endregion
2228
2258
  //#region src/response-error.d.ts
2229
2259
  interface ResponseErrorPayload {
@@ -2711,4 +2741,4 @@ declare const parseBodyText: (text: string, route: RouteDefinition) => unknown;
2711
2741
  declare const parseFetchBody: (request: Request, route: RouteDefinition) => Promise<unknown>;
2712
2742
  declare const headersToObject: (headers: Headers) => ResponseHeaders;
2713
2743
  //#endregion
2714
- export { jobRunnerFrom as $, StreamMessage as $i, jobAt as $n, ContextFromAuth as $r, ResolvedPlugin as $t, RenderedResult as A, Credential as Aa, ToolDefinition as Ai, SchemesOf as An, scheduleExpression as Ar, shortTypeName as At, bearerChallenge as B, OpenIdConnectConfig as Ba, PathParamName as Bi, JobHandlerArgs as Bn, createTags as Br, PluginArgs as Bt, JOBS_META as C, withPermissions as Ca, ModelToolCall as Ci, apiEntries as Cn, assertValidSchedule as Cr, resolveResponseCache as Ct, REQUEST_CONTEXT_META as D, BasicCredential as Da, ToolRunCall as Di, JobsOf as Dn, nextRun as Dr, resolveResponseStream as Dt, MountedOf as E, BasicConfig as Ea, ToolEventYield as Ei, GuardSchemaOf as En, firesBetween as Er, resolveResponseHeaders as Et, RouteMatcher as F, Identity as Fa, selectToolRoutes as Fi, FlattenedJob as Fn, RequestContextSchema as Fr, ApiPlugins as Ft, dispatchRoute as G, parsePath as Gi, JobVoidReturn as Gn, RouteBuilder as Gr, PluginFactory as Gt, contractOf as H, RolesOf as Ha, PathSegment as Hi, JobHandlers as Hn, RawResponse as Hr, PluginDefinition as Ht, SCHEMES_META as I, IdentityParamsOf as Ia, toolOptionsOf as Ii, HttpJobsConfig as In, NormalizeTags as Ir, InstallOptions as It, guardDenyFor as J, StreamBody as Ji, JobsConfig as Jn, RouteMatch as Jr, PluginRoutes as Jt, extractCredential as K, EVENT_STREAM_MEDIA_TYPE as Ki, Jobs as Kn, RouteWithHandler as Kr, PluginList as Kt, ServerOptions as L, IdentityRole as La, toolRefusal as Li, InProcessJobsConfig as Ln, TagKeysOf as Lr, PLUGIN_ROUTES_META_KEY as Lt, RequestContextRun as M, CustomConfig as Ma, buildToolDefinitions as Mi, AuthoredJobs as Mn, RequestContextConfig as Mr, toCamelCase as Mt, RequestPipeline as N, GrantsOf as Na, buildToolInputSchema as Ni, CompiledJob as Nn, RequestContextHeaderInputs as Nr, toPascalCase as Nt, ROUTER_META as O, BearerConfig as Oa, ToolRunOptions as Oi, RequestContextOf as On, nextRuns as Or, sanitizeFieldName as Ot, ResponseValidationError as P, GuardHoldings as Pa, describeTool as Pi, CompiledJobs as Pn, RequestContextHeaderValues as Pr, AnyPlugin as Pt, jobRoutes as Q, StreamContext as Qi, isJobDefinition as Qn, BrandedHandlerContext as Qr, PluginsBySlug as Qt, adapterContextOf as R, NoCredential as Ra, ExtractPathParams as Ri, JobDefinition as Rn, TagOptions as Rr, PLUGIN_SERVERS_META_KEY as Rt, HandlerContextOf as S, requiresDenial as Sa, validateRequest as Si, GeneratedFile as Sn, ParsedCron as Sr, resolveResponseBody as St, MountArgsOf as T, ApiKeyCredential as Ta, ToolAnswer as Ti, ApiPluginsOf as Tn, dueSchedules as Tr, resolveResponseEtag as Tt, defineAdapter as U, RoutePathParamsCheck as Ui, JobResponses as Un, isRawResponse as Ur, PluginExportValues as Ut, boundJobKeys as V, RoleOf as Va, PathParamsCheck as Vi, JobHandlerReturn as Vn, isTagSet as Vr, PluginDeclaration as Vt, dispatchHandler as W, buildPath as Wi, JobRunnerConfig as Wn, rawResponse as Wr, PluginExportsOf as Wt, isGuardDenial as X, StreamChunk as Xi, flattenJobs as Xn, sortFlattenedRoutes as Xr, PluginSetup as Xt, headersToObject as Y, StreamBodyOf as Yi, NoJobs as Yn, matchRoute as Yr, PluginRoutesOf as Yt, jobRouter as Z, StreamComment as Zi, isCompiledJob as Zn, AuthContextOf as Zr, PluginSetupContext as Zt, GuardDeny as _, ToolResult as _a, ValidationStage as _i, JobFnOf as _n, JobWorker as _r, isStreamResponse as _t, AdapterRequest as a, routeStreams as aa, GuardedParamNames as ai, route as an, JobQueueOptions as ar, runRoute as at, HANDLER_ARG_KEYS as b, AccessCheckInput as ba, formatValidationError as bi, ApiEntry as bn, defineJobTransport as br, localTypeName as bt, ApiBrand as c, streamMode as ca, HandlersFromRoutes as ci, ConfiguredAdapterValue as cn, JobRunnerOptions as cr, ResponseError as ct, DISPATCH_ROUTE_KEY as d, StreamWithTools as da, RouteGuardBrandOf as di, ConfiguredIdentities as dn, JobDescriptor as dr, pluginExportsOf as dt, StreamMessageOf as ea, FlattenedRoute as ei, RouteAuthSchema as en, JobErrorHandler as er, parseBodyText as et, ErrorFormatter as f, ToolAt as fa, RouteHandler as fi, ConfiguredJobs as fn, JobDispatchError as fr, pluginRouterOf as ft, GuardDenialBody as g, ToolKeys as ga, ValidationFailure as gi, ConfiguredTags as gn, JobTransportSupports as gr, isJsonMediaType as gt, GuardDenial as h, ToolEvents as ha, ThrowableReturn as hi, ConfiguredRequestContextSchemas as hn, JobTransportDefinition as hr, isHintPrefix as ht, AdapterDefinition as i, isNamedStream as ia, GuardSuccess as ii, pluginRouteTree as in, JobQueueArgs as ir, runHandler as it, RequestContextMap as j, CredentialOf as ja, ToolInputSchema as ji, AuthoredJobDefinition as jn, scheduleTimezone as jr, statusToCamelCase as jt, RUN_ROUTE_KEY as k, BearerCredential as ka, ToolRunResult as ki, RoutesOf as kn, parseCron as kr, sanitizeIdentifier as kt, ApiParts as l, streamSchemas as la, RawInputs as li, ConfiguredCodes as ln, createJobRunner as lr, tagRoutes as lt, GUARD_SCHEMA_META as m, ToolError as ma, RoutesWithHandlerContext as mi, ConfiguredRequestContext as mn, JobTransport as mr, resolvePlugins as mt, API_META as n, StreamYield as na, GuardParams as ni, SlugOption as nn, JobFnByKey as nr, renderJsonResult as nt, AdapterResult as o, soleStreamResponse as oa, HandlerArgs as oi, ApiContext as on, JobRunArgs as or, warnUnsupportedJobOptions as ot, GUARDS_META as p, ToolCall as pa, Router as pi, ConfiguredPlugins as pn, JobMessage as pr, pluginRoutesOf as pt, getHeaderValue as q, EncodeStreamOptions as qi, JobsArg as qn, MatchResult as qr, PluginRouteBuilder as qt, Adapter as r, encodeStreamBody as ra, GuardReturn as ri, definePlugin as rn, JobInputError as rr, routerFromRoutes as rt, AnyAdapter as s, streamContentType as sa, HandlerReturn as si, ConfiguredAdapterContext as sn, JobRunner as sr, ApiRouter as st, ADAPTER_CONTEXT as t, StreamMode as ta, GuardAnswer as ti, RoutePathSchema as tn, JobFn as tr, parseFetchBody as tt, ApiWithRouter as u, streamStatuses as ua, RequestContextValues as ui, ConfiguredGuardSchema as un, jobFnAt as ur, createApiReference as ut, GuardMap as v, expandStreamTools as va, allowedMethodsForPath as vi, JobsOfTree as vn, JobWorkerContext as vr, isSuccessStatus as vt, JobsMeta as w, ApiKeyConfig as wa, StreamTools as wi, ApiDefinition as wn, cron as wr, resolveResponseContentType as wt, HandleArgs as x, insufficientScope as xa, isRouteDefinition as xi, DiffSettings as xn, JobSchedule as xr, mergeHeaderFields as xt, GuardRun as y, toolEvents as ya, flattenRoutes as yi, KizunaConfigShape as yn, ScheduledJob as yr, isZodSchema as yt, assembleApi as z, OAuth2Config as za, HasPathParams as zi, JobHandler as zn, TagSet as zr, PluginApi as zt };
2744
+ export { jobRunnerFrom as $, StreamContext as $i, jobAt as $n, BrandedHandlerContext as $r, ResolvedPlugin as $t, RenderedResult as A, BearerCredential as Aa, ToolRunResult as Ai, SchemesOf as An, scheduleExpression as Ar, shortTypeName as At, bearerChallenge as B, OAuth2Config as Ba, HasPathParams as Bi, JobHandlerArgs as Bn, ResolvedGroup as Br, PluginArgs as Bt, JOBS_META as C, requiresDenial as Ca, validateRequest as Ci, apiEntries as Cn, assertValidSchedule as Cr, resolveResponseCache as Ct, REQUEST_CONTEXT_META as D, BasicConfig as Da, ToolEventYield as Di, JobsOf as Dn, nextRun as Dr, resolveResponseStream as Dt, MountedOf as E, ApiKeyCredential as Ea, ToolAnswer as Ei, GuardSchemaOf as En, firesBetween as Er, resolveResponseHeaders as Et, RouteMatcher as F, GuardHoldings as Fa, describeTool as Fi, FlattenedJob as Fn, RequestContextSchema as Fr, ApiPlugins as Ft, dispatchRoute as G, buildPath as Gi, JobVoidReturn as Gn, rawResponse as Gr, PluginFactory as Gt, contractOf as H, RoleOf as Ha, PathParamsCheck as Hi, JobHandlers as Hn, isGroupSet as Hr, PluginDefinition as Ht, SCHEMES_META as I, Identity as Ia, selectToolRoutes as Ii, HttpJobsConfig as In, GroupOptions as Ir, InstallOptions as It, guardDenyFor as J, EncodeStreamOptions as Ji, JobsConfig as Jn, MatchResult as Jr, PluginRoutes as Jt, extractCredential as K, parsePath as Ki, Jobs as Kn, RouteBuilder as Kr, PluginList as Kt, ServerOptions as L, IdentityParamsOf as La, toolOptionsOf as Li, InProcessJobsConfig as Ln, GroupPaths as Lr, PLUGIN_ROUTES_META_KEY as Lt, RequestContextRun as M, CredentialOf as Ma, ToolInputSchema as Mi, AuthoredJobs as Mn, RequestContextConfig as Mr, toCamelCase as Mt, RequestPipeline as N, CustomConfig as Na, buildToolDefinitions as Ni, CompiledJob as Nn, RequestContextHeaderInputs as Nr, toPascalCase as Nt, ROUTER_META as O, BasicCredential as Oa, ToolRunCall as Oi, RequestContextOf as On, nextRuns as Or, sanitizeFieldName as Ot, ResponseValidationError as P, GrantsOf as Pa, buildToolInputSchema as Pi, CompiledJobs as Pn, RequestContextHeaderValues as Pr, AnyPlugin as Pt, jobRoutes as Q, StreamComment as Qi, isJobDefinition as Qn, AuthContextOf as Qr, PluginsBySlug as Qt, adapterContextOf as R, IdentityRole as Ra, toolRefusal as Ri, JobDefinition as Rn, GroupPathsOf as Rr, PLUGIN_SERVERS_META_KEY as Rt, HandlerContextOf as S, insufficientScope as Sa, isRouteDefinition as Si, GeneratedFile as Sn, ParsedCron as Sr, resolveResponseBody as St, MountArgsOf as T, ApiKeyConfig as Ta, StreamTools as Ti, ApiPluginsOf as Tn, dueSchedules as Tr, resolveResponseEtag as Tt, defineAdapter as U, RolesOf as Ua, PathSegment as Ui, JobResponses as Un, RawResponse as Ur, PluginExportValues as Ut, boundJobKeys as V, OpenIdConnectConfig as Va, PathParamName as Vi, JobHandlerReturn as Vn, createGroups as Vr, PluginDeclaration as Vt, dispatchHandler as W, RoutePathParamsCheck as Wi, JobRunnerConfig as Wn, isRawResponse as Wr, PluginExportsOf as Wt, isGuardDenial as X, StreamBodyOf as Xi, flattenJobs as Xn, matchRoute as Xr, PluginSetup as Xt, headersToObject as Y, StreamBody as Yi, NoJobs as Yn, RouteMatch as Yr, PluginRoutesOf as Yt, jobRouter as Z, StreamChunk as Zi, isCompiledJob as Zn, sortFlattenedRoutes as Zr, PluginSetupContext as Zt, GuardDeny as _, ToolKeys as _a, ValidationFailure as _i, JobFnOf as _n, JobWorker as _r, isStreamResponse as _t, AdapterRequest as a, isNamedStream as aa, GuardSuccess as ai, route as an, JobQueueOptions as ar, runRoute as at, HANDLER_ARG_KEYS as b, toolEvents as ba, flattenRoutes as bi, ApiEntry as bn, defineJobTransport as br, localTypeName as bt, ApiBrand as c, streamContentType as ca, HandlerReturn as ci, ConfiguredAdapterValue as cn, JobRunnerOptions as cr, ResponseError as ct, DISPATCH_ROUTE_KEY as d, streamStatuses as da, RequestContextValues as di, ConfiguredGuardSchema as dn, JobDescriptor as dr, pluginExportsOf as dt, StreamMessage as ea, ContextFromAuth as ei, RouteAuthSchema as en, JobErrorHandler as er, parseBodyText as et, ErrorFormatter as f, StreamWithTools as fa, RouteGuardBrandOf as fi, ConfiguredIdentities as fn, JobDispatchError as fr, pluginRouterOf as ft, GuardDenialBody as g, ToolEvents as ga, ThrowableReturn as gi, ConfiguredRequestContextSchemas as gn, JobTransportSupports as gr, isJsonMediaType as gt, GuardDenial as h, ToolError as ha, RoutesWithHandlerContext as hi, ConfiguredRequestContext as hn, JobTransportDefinition as hr, isHintPrefix as ht, AdapterDefinition as i, encodeStreamBody as ia, GuardReturn as ii, pluginRouteTree as in, JobQueueArgs as ir, runHandler as it, RequestContextMap as j, Credential as ja, ToolDefinition as ji, AuthoredJobDefinition as jn, scheduleTimezone as jr, statusToCamelCase as jt, RUN_ROUTE_KEY as k, BearerConfig as ka, ToolRunOptions as ki, RoutesOf as kn, parseCron as kr, sanitizeIdentifier as kt, ApiParts as l, streamMode as la, HandlersFromRoutes as li, ConfiguredCodes as ln, createJobRunner as lr, groupRoutes as lt, GUARD_SCHEMA_META as m, ToolCall as ma, Router as mi, ConfiguredPlugins as mn, JobTransport as mr, resolvePlugins as mt, API_META as n, StreamMode as na, GuardAnswer as ni, SlugOption as nn, JobFnByKey as nr, renderJsonResult as nt, AdapterResult as o, routeStreams as oa, GuardedParamNames as oi, ApiContext as on, JobRunArgs as or, warnUnsupportedJobOptions as ot, GUARDS_META as p, ToolAt as pa, RouteHandler as pi, ConfiguredJobs as pn, JobMessage as pr, pluginRoutesOf as pt, getHeaderValue as q, EVENT_STREAM_MEDIA_TYPE as qi, JobsArg as qn, RouteWithHandler as qr, PluginRouteBuilder as qt, Adapter as r, StreamYield as ra, GuardParams as ri, definePlugin as rn, JobInputError as rr, routerFromRoutes as rt, AnyAdapter as s, soleStreamResponse as sa, HandlerArgs as si, ConfiguredAdapterContext as sn, JobRunner as sr, ApiRouter as st, ADAPTER_CONTEXT as t, StreamMessageOf as ta, FlattenedRoute as ti, RoutePathSchema as tn, JobFn as tr, parseFetchBody as tt, ApiWithRouter as u, streamSchemas as ua, RawInputs as ui, ConfiguredGroups as un, jobFnAt as ur, createApiReference as ut, GuardMap as v, ToolResult as va, ValidationStage as vi, JobsOfTree as vn, JobWorkerContext as vr, isSuccessStatus as vt, JobsMeta as w, withPermissions as wa, ModelToolCall as wi, ApiDefinition as wn, cron as wr, resolveResponseContentType as wt, HandleArgs as x, AccessCheckInput as xa, formatValidationError as xi, DiffSettings as xn, JobSchedule as xr, mergeHeaderFields as xt, GuardRun as y, expandStreamTools as ya, allowedMethodsForPath as yi, KizunaConfigShape as yn, ScheduledJob as yr, isZodSchema as yt, assembleApi as z, NoCredential as za, ExtractPathParams as zi, JobHandler as zn, GroupSet as zr, PluginApi as zt };