kizunajs 2.0.0-beta.2 → 2.0.0-beta.21

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 (81) hide show
  1. package/README.md +3 -2
  2. package/dist/{adapter-CZW-unqX.mjs → adapter-BSqNrxhq.mjs} +522 -104
  3. package/dist/adapter-C3WYdSfx.d.cts +2754 -0
  4. package/dist/{adapter-DDR_yo9L.cjs → adapter-ClaFZoab.cjs} +638 -196
  5. package/dist/adapter-D4bTPElA.d.mts +2754 -0
  6. package/dist/adapter.cjs +37 -29
  7. package/dist/adapter.d.cts +3 -5
  8. package/dist/adapter.d.mts +3 -5
  9. package/dist/adapter.mjs +5 -5
  10. package/dist/{error-response-C8Ragjcd.cjs → error-response-C9ymqSU4.cjs} +25 -5
  11. package/dist/{error-response-C839d8By.mjs → error-response-CNQaKVYd.mjs} +20 -6
  12. package/dist/{security-scheme-BrszwGD5.d.cts → error-response-NoOGdh8H.d.mts} +151 -24
  13. package/dist/{security-scheme-D3nb4XKj.d.mts → error-response-YbkRMKno.d.cts} +151 -24
  14. package/dist/generator.cjs +190 -95
  15. package/dist/generator.d.cts +189 -28
  16. package/dist/generator.d.mts +189 -28
  17. package/dist/generator.mjs +151 -60
  18. package/dist/index.cjs +159 -84
  19. package/dist/index.d.cts +193 -253
  20. package/dist/index.d.mts +193 -253
  21. package/dist/index.mjs +112 -38
  22. package/dist/jobs-entry.cjs +12 -11
  23. package/dist/jobs-entry.d.cts +1 -1
  24. package/dist/jobs-entry.d.mts +1 -1
  25. package/dist/jobs-entry.mjs +3 -2
  26. package/dist/plugin-Dw-yCjTY.cjs +233 -0
  27. package/dist/{cache-CLN5y0Xp.mjs → plugin-server-BztlE1fz.mjs} +188 -49
  28. package/dist/{cache-BgohRj0i.cjs → plugin-server-kUsK7thV.cjs} +238 -93
  29. package/dist/plugin-xxCxibmu.mjs +138 -0
  30. package/dist/plugin.cjs +8 -72
  31. package/dist/plugin.d.cts +3 -3
  32. package/dist/plugin.d.mts +3 -3
  33. package/dist/plugin.mjs +2 -68
  34. package/dist/{protected-resource-metadata-CA0v5cjg.d.mts → protected-resource-metadata-B9hMFQ9N.d.cts} +1 -1
  35. package/dist/{protected-resource-metadata-Cprrv0mt.d.cts → protected-resource-metadata-CfBVsqIk.d.mts} +1 -1
  36. package/dist/{schemas-C56no6bv.cjs → schemas-DNPVDvkd.cjs} +28 -1
  37. package/dist/{schemas-CJQcc97N.mjs → schemas-HW2FDsvz.mjs} +23 -2
  38. package/dist/schemas.cjs +3 -2
  39. package/dist/schemas.d.cts +24 -3
  40. package/dist/schemas.d.mts +24 -3
  41. package/dist/schemas.mjs +3 -3
  42. package/package.json +1 -1
  43. package/src/adapter.ts +245 -29
  44. package/src/api-definition.ts +12 -16
  45. package/src/api.ts +7 -3
  46. package/src/brand.ts +29 -0
  47. package/src/config.ts +51 -10
  48. package/src/configured.ts +13 -6
  49. package/src/define-config.ts +118 -39
  50. package/src/generator.ts +363 -46
  51. package/src/group-routes.ts +106 -0
  52. package/src/groups.ts +140 -0
  53. package/src/handler-pipeline.ts +78 -19
  54. package/src/index.ts +15 -6
  55. package/src/job-runner.ts +5 -0
  56. package/src/job-transport.ts +3 -3
  57. package/src/job.ts +8 -6
  58. package/src/jobs-dev-runner.ts +6 -0
  59. package/src/jobs.ts +61 -8
  60. package/src/kizuna.ts +56 -33
  61. package/src/plugin-server.ts +129 -19
  62. package/src/plugin.ts +269 -127
  63. package/src/routes.ts +80 -32
  64. package/src/schemas.ts +1 -0
  65. package/src/tool-answer.ts +21 -0
  66. package/src/tool-definitions.ts +166 -0
  67. package/src/tool-events.ts +90 -18
  68. package/src/tool-records.ts +11 -3
  69. package/src/tool-runner.ts +298 -0
  70. package/src/types.ts +90 -24
  71. package/src/zod-internals.ts +22 -5
  72. package/src/zod-meta.ts +7 -2
  73. package/dist/adapter-BGfMqEkM.d.cts +0 -563
  74. package/dist/adapter-Ci3cfcoT.d.mts +0 -563
  75. package/dist/api-definition-BHnh15zD.d.mts +0 -803
  76. package/dist/api-definition-DQj-ewHy.d.cts +0 -803
  77. package/dist/error-response-BBGSdgYw.d.mts +0 -67
  78. package/dist/error-response-Do38sr-9.d.cts +0 -67
  79. package/dist/plugin-Cz0kn6Lk.d.mts +0 -830
  80. package/dist/plugin-DhKvx_T0.d.cts +0 -830
  81. package/src/tags.ts +0 -67
package/dist/index.d.cts CHANGED
@@ -1,15 +1,17 @@
1
- import { $ as GuardBody, A as DECLARATION, B as ResponseContentType, C as AUTO_GUARD_BRAND, D as AuthoredRoutes, E as AuthoredRouteDefinition, F as HandlerContextBrand, G as RouteHandlerFunction, I as METHODS, J as Routes, K as RoutePath, L as Method, M as GuardStatus, N as HANDLER, O as AutoResponsesBrand, P as HANDLER_CONTEXT_BRAND, Q as StreamResponseDefinition, S as isRoles, T as AUTO_RESPONSES_BRAND, U as RouteAuth, V as ResponseDefinition, W as RouteDefinition, X as SecurityRequirement, Y as SchemeNameOf, Z as StreamDefinition, _ as RoleDefinition, a as SecurityScheme, at as problemFromBody, b as createRoles, c as declaredScopes, d as CatalogOf, et as GuardOutput, f as GrantNamesOf, g as Permissions, h as PermissionSet, i as OpenApiSecuritySchemeObject, it as problemDetails, j as DeclarationKind, k as CachePolicy, l as isSecurityScheme, m as PermissionName, n as OAuthFlow, nt as ProblemDetails, ot as STATUS_TITLES, p as PermissionCatalog, q as RouteToolOptions, r as OAuthFlows, rt as StripProblemEnvelope, s as authorizationServerIssuer, st as getStatusText, t as ContextOf, tt as GuardSchemaCheck, v as RoleNamesOf, w as AUTO_GUARD_WRITTEN_BRAND, x as isPermissions, y as Roles, z as RequiredPermissions } from "./security-scheme-BrszwGD5.cjs";
2
- import { $ as PathParamsCheck, A as GuardReturn, At as expandStreamTools, Bt as CustomConfig, Ct as StreamWithTools, Dt as ToolEvents, E as ContextFromAuth, Et as ToolError, Ft as BasicCredential, Gt as IdentityRole, H as ThrowableReturn, Ht as GuardHoldings, It as BearerConfig, J as isRouteDefinition, Jt as OpenIdConnectConfig, Kt as NoCredential, L as RequestContextValues, Lt as BearerCredential, Mt as ApiKeyConfig, N as HandlerArgs, Nt as ApiKeyCredential, O as GuardAnswer, Ot as ToolKeys, P as HandlerReturn, Pt as BasicConfig, Q as PathParamName, R as RouteGuardBrandOf, Rt as Credential, St as streamStatuses, T as BrandedHandlerContext, Tt as ToolCall, Ut as Identity, V as RoutesWithHandlerContext, Vt as GrantsOf, Wt as IdentityParamsOf, X as ExtractPathParams, Xt as RolesOf, Yt as RoleOf, Z as HasPathParams, _t as routeStreams, a as PluginArgs, bt as streamMode, c as PluginExportValues, ct as StreamChunk, d as PluginPropsOf, dt as StreamMessage, ft as StreamMessageOf, g as PluginsBySlug, gt as isNamedStream, it as EVENT_STREAM_MEDIA_TYPE, j as GuardSuccess, jt as toolEvents, kt as ToolResult, l as PluginExportsOf, lt as StreamComment, m as PluginRoutesOf, mt as StreamYield, n as ApiPlugins, nt as buildPath, o as PluginDeclaration, ot as StreamBody, p as PluginRoutes, pt as StreamMode, qt as OAuth2Config, rt as parsePath, s as PluginDefinition, st as StreamBodyOf, t as AnyPlugin, tt as RoutePathParamsCheck, u as PluginList, ut as StreamContext, v as createPlugin, vt as soleStreamResponse, w as AuthContextOf, wt as ToolAt, yt as streamContentType, z as RouteHandler, zt as CredentialOf } from "./plugin-DhKvx_T0.cjs";
3
- import { E as MountedOf, S as HandlerContextOf, T as MountArgsOf, _ as GuardDeny, h as GuardDenial, q as getHeaderValue, s as AnyAdapter, st as ResponseError, u as ApiWithRouter } from "./adapter-BGfMqEkM.cjs";
4
- import { n as isProblemDetails } from "./error-response-Do38sr-9.cjs";
5
- import { $ as NoJobs, At as firesBetween, B as CompiledJobs, Ct as ScheduledJob, Dt as assertValidSchedule, Et as ParsedCron, Ft as scheduleTimezone, G as JobHandlerReturn, H as JobDefinition, J as JobRunnerConfig, K as JobHandlers, L as AuthoredJobDefinition, Mt as nextRuns, Nt as parseCron, Ot as cron, Pt as scheduleExpression, Q as JobsConfig, R as AuthoredJobs, S as isZodSchema, St as JobWorkerContext, Tt as JobSchedule, U as JobHandler, V as FlattenedJob, W as JobHandlerArgs, X as Jobs, Y as JobVoidReturn, Z as JobsArg, _t as JobMessage, a as RequestContextOf, at as JobFn, b as isStreamResponse, bt as JobTransportSupports, c as RequestContextConfig, ct as JobQueueArgs, d as RequestContextSchema, dt as JobRunner, et as flattenJobs, f as NormalizeTags, ft as JobRunnerOptions, g as createTags, gt as JobDispatchError, h as TagSet, ht as JobDescriptor, i as JobsOf, it as JobErrorHandler, jt as nextRun, kt as dueSchedules, l as RequestContextHeaderInputs, lt as JobQueueOptions, m as TagOptions, mt as jobFnAt, n as ApiPluginsOf, nt as isJobDefinition, o as RoutesOf, ot as JobFnByKey, p as TagKeysOf, pt as createJobRunner, q as JobResponses, r as GuardSchemaOf, rt as jobAt, s as SchemesOf, st as JobInputError, t as ApiDefinition, tt as isCompiledJob, u as RequestContextHeaderValues, ut as JobRunArgs, vt as JobTransport, wt as createJobTransport, xt as JobWorker, yt as JobTransportDefinition, z as CompiledJob } from "./api-definition-DQj-ewHy.cjs";
6
- import { a as buildProtectedResourceMetadata, c as ValidationErrorFor, d as isValidationError, i as assertCanonicalResourceUri, n as ProtectedResourceMetadata, o as BuiltinIssueCode, s as ValidationError, t as ProtectedResourceConfig, u as ValidationIssueCode } from "./protected-resource-metadata-Cprrv0mt.cjs";
1
+ import { $ as SecurityRequirement, A as AutoResponsesBrand, B as ROUTES_GROUP, C as isPermissions, D as AUTO_RESPONSES_BRAND, E as AUTO_GUARD_WRITTEN_BRAND, F as HANDLER, G as RouteAuth, H as ResponseContentType, I as HANDLER_CONTEXT_BRAND, J as RouteHiddenToolCheck, K as RouteDefinition, L as HandlerContextBrand, M as DECLARATION, N as DeclarationKind, O as AuthoredRouteDefinition, P as GuardStatus, Q as SchemeNameOf, R as METHODS, S as createRoles, T as AUTO_GUARD_BRAND, U as ResponseDefinition, V as RequiredPermissions, X as RouteToolOptions, Y as RoutePath, Z as Routes, _ as PermissionSet, a as OAuthFlows, at as ProblemDetails, b as RoleNamesOf, ct as problemFromBody, d as isSecurityScheme, et as StreamDefinition, g as PermissionName, h as PermissionCatalog, i as OAuthFlow, it as GuardSchemaCheck, j as CachePolicy, k as AuthoredRoutes, l as authorizationServerIssuer, lt as STATUS_TITLES, m as GrantNamesOf, n as isProblemDetails, nt as GuardBody, o as OpenApiSecuritySchemeObject, ot as StripProblemEnvelope, p as CatalogOf, q as RouteHandlerFunction, r as ContextOf, rt as GuardOutput, s as SecurityScheme, st as problemDetails, tt as StreamResponseDefinition, u as declaredScopes, ut as getStatusText, v as Permissions, w as isRoles, x as Roles, y as RoleDefinition, z as Method } from "./error-response-YbkRMKno.cjs";
2
+ import { $i as StreamContext, $n as jobAt, $r as BrandedHandlerContext, Aa as BearerCredential, Ai as ToolRunResult, An as SchemesOf, Ar as scheduleExpression, Ba as OAuth2Config, Bi as HasPathParams, Bn as JobHandlerArgs, Br as ResolvedGroup, Bt as PluginArgs, Cn as apiEntries, Cr as assertValidSchedule, Da as BasicConfig, Di as ToolEventYield, Dn as JobsOf, Dr as nextRun, E as MountedOf, Ea as ApiKeyCredential, Ei as ToolAnswer, En as GuardSchemaOf, Er as firesBetween, Fa as GuardHoldings, Fn as FlattenedJob, Fr as RequestContextSchema, Ft as ApiPlugins, Gi as buildPath, Gn as JobVoidReturn, Gt as PluginFactory, Ha as RoleOf, Hi as PathParamsCheck, Hn as JobHandlers, Ht as PluginDefinition, Ia as Identity, In as HttpJobsConfig, Ir as GroupOptions, Jn as JobsConfig, Jt as PluginRoutes, Ki as parsePath, Kn as Jobs, Kr as RouteBuilder, Kt as PluginList, La as IdentityParamsOf, Ln as InProcessJobsConfig, Lr as GroupPaths, Ma as CredentialOf, Mn as AuthoredJobs, Mr as RequestContextConfig, Na as CustomConfig, Nn as CompiledJob, Nr as RequestContextHeaderInputs, Oa as BasicCredential, Oi as ToolRunCall, On as RequestContextOf, Or as nextRuns, Pa as GrantsOf, Pn as CompiledJobs, Pr as RequestContextHeaderValues, Pt as AnyPlugin, Qi as StreamComment, Qn as isJobDefinition, Qr as AuthContextOf, Qt as PluginsBySlug, Ra as IdentityRole, Rn as JobDefinition, Rr as GroupPathsOf, Si as isRouteDefinition, Sn as GeneratedFile, Sr as ParsedCron, T as MountArgsOf, Ta as ApiKeyConfig, Ti as StreamTools, Tn as ApiPluginsOf, Tr as dueSchedules, Ua as RolesOf, Un as JobResponses, Ut as PluginExportValues, Va as OpenIdConnectConfig, Vi as PathParamName, Vn as JobHandlerReturn, Vr as createGroups, Vt as PluginDeclaration, Wi as RoutePathParamsCheck, Wn as JobRunnerConfig, Wt as PluginExportsOf, Xi as StreamBodyOf, Xn as flattenJobs, Xt as PluginSetup, Yi as StreamBody, Yn as NoJobs, Yt as PluginRoutesOf, Zi as StreamChunk, Zn as isCompiledJob, Zt as PluginSetupContext, _ as GuardDeny, _a as ToolKeys, _n as JobFnOf, _r as JobWorker, _t as isStreamResponse, aa as isNamedStream, ai as GuardSuccess, ar as JobQueueOptions, ba as toolEvents, bn as ApiEntry, br as defineJobTransport, ca as streamContentType, ci as HandlerReturn, cn as ConfiguredAdapterValue, cr as JobRunnerOptions, ct as ResponseError, da as streamStatuses, dn as ConfiguredGuardSchema, dr as JobDescriptor, ea as StreamMessage, ei as ContextFromAuth, er as JobErrorHandler, fa as StreamWithTools, fi as RouteGuardBrandOf, fn as ConfiguredIdentities, fr as JobDispatchError, ga as ToolEvents, gi as ThrowableReturn, gn as ConfiguredRequestContextSchemas, gr as JobTransportSupports, h as GuardDenial, ha as ToolError, hi as RoutesWithHandlerContext, hn as ConfiguredRequestContext, hr as JobTransportDefinition, ii as GuardReturn, ir as JobQueueArgs, ja as Credential, ji as ToolDefinition, jn as AuthoredJobDefinition, jr as scheduleTimezone, ka as BearerConfig, ki as ToolRunOptions, kn as RoutesOf, kr as parseCron, la as streamMode, ln as ConfiguredCodes, lr as createJobRunner, ma as ToolCall, mn as ConfiguredPlugins, mr as JobTransport, na as StreamMode, ni as GuardAnswer, nr as JobFnByKey, oa as routeStreams, or as JobRunArgs, pa as ToolAt, pn as ConfiguredJobs, pr as JobMessage, q as getHeaderValue, qi as EVENT_STREAM_MEDIA_TYPE, qn as JobsArg, qr as RouteWithHandler, ra as StreamYield, rn as definePlugin, rr as JobInputError, s as AnyAdapter, sa as soleStreamResponse, si as HandlerArgs, sn as ConfiguredAdapterContext, sr as JobRunner, ta as StreamMessageOf, tr as JobFn, u as ApiWithRouter, un as ConfiguredGroups, ur as jobFnAt, va as ToolResult, vn as JobsOfTree, vr as JobWorkerContext, wi as ModelToolCall, wn as ApiDefinition, wr as cron, xn as DiffSettings, xr as JobSchedule, ya as expandStreamTools, yn as KizunaConfigShape, yr as ScheduledJob, yt as isZodSchema, za as NoCredential, zi as ExtractPathParams, zn as JobHandler, zr as GroupSet, zt as PluginApi } from "./adapter-C3WYdSfx.cjs";
3
+ import { a as buildProtectedResourceMetadata, c as ValidationErrorFor, d as isValidationError, i as assertCanonicalResourceUri, n as ProtectedResourceMetadata, o as BuiltinIssueCode, s as ValidationError, t as ProtectedResourceConfig, u as ValidationIssueCode } from "./protected-resource-metadata-B9hMFQ9N.cjs";
7
4
  import { z } from "zod";
8
- import { $output } from "zod/v4/core";
5
+ import { $input, $output } from "zod/v4/core";
9
6
 
10
7
  //#region src/zod-meta.d.ts
11
8
  declare module 'zod/v4/core' {
12
9
  interface GlobalMeta {
10
+ /**
11
+ * The brand generated clients give this schema's values. Set by
12
+ * `Kizuna.brand`.
13
+ */
14
+ brand?: string;
13
15
  /**
14
16
  * Deprecates the schema. Pass a message to tell callers what to use
15
17
  * instead.
@@ -24,7 +26,7 @@ declare module 'zod/v4/core' {
24
26
  * example: 'ada@example.com',
25
27
  * });
26
28
  */
27
- example?: $output | $output[];
29
+ example?: $input | $output | Array<$input | $output>;
28
30
  }
29
31
  }
30
32
  //#endregion
@@ -47,6 +49,99 @@ interface ModelOptions<T extends z.ZodType> {
47
49
  schema: T;
48
50
  }
49
51
  //#endregion
52
+ //#region src/brand.d.ts
53
+ /**
54
+ * What a brand wraps. Every client can give a scalar a type of its own.
55
+ */
56
+ type BrandableSchema = z.ZodType<string | number | bigint | boolean | Date>;
57
+ //#endregion
58
+ //#region src/auth-check.d.ts
59
+ /**
60
+ * The role names an identity accepts, or `never` when it declares none.
61
+ */
62
+ type AcceptedRolesOf$1<Identities, Name extends string> = Name extends keyof Identities ? [RoleNamesOf<RolesOf<Identities[Name]>>] extends [never] ? never : RoleNamesOf<RolesOf<Identities[Name]>> : never;
63
+ /**
64
+ * The identity names one `auth` value requires.
65
+ */
66
+ type NamesIn<Value> = Value extends string ? Value : Value extends readonly (infer Name extends string)[] ? Name : Value extends {
67
+ identity: infer Identity;
68
+ } ? Identity extends string ? Identity : Identity extends readonly (infer Name extends string)[] ? Name : never : never;
69
+ type RoleMismatch<Value, Identities> = Value extends {
70
+ roles: infer Declared;
71
+ } ? Exclude<Declared extends readonly (infer Role)[] ? Role : Declared, AcceptedRolesOf$1<Identities, NamesIn<Value>>> & string : never;
72
+ /**
73
+ * The verbs every identity on the route declares for one resource.
74
+ */
75
+ type VerbsFor<Identities, Names extends string, Resource extends string> = CatalogsOf<Identities, Names> extends infer Catalog ? Catalog extends Record<string, readonly string[]> ? Resource extends keyof Catalog ? Catalog[Resource][number] : never : never : never;
76
+ type CatalogsOf<Identities, Names extends string> = Names extends keyof Identities ? CatalogOf<RolesOf<Identities[Names]>> : never;
77
+ type RequiresMismatch<Value, Identities> = Value extends {
78
+ requires: infer Declared;
79
+ } ? { [Resource in keyof Declared & string]: Declared[Resource] extends readonly (infer Verb extends string)[] ? Verb extends VerbsFor<Identities, NamesIn<Value>, Resource> ? never : `${Resource}:${Verb}` : never }[keyof Declared & string] : never;
80
+ /**
81
+ * What is wrong with one route's `auth`, as a message, or `never` when it is
82
+ * sound.
83
+ */
84
+ type AuthMismatch<Route, Identities> = Route extends {
85
+ auth: infer Value;
86
+ } ? [RoleMismatch<Value, Identities>] extends [never] ? [RequiresMismatch<Value, Identities>] extends [never] ? never : `kizuna: auth requires "${RequiresMismatch<Value, Identities>}", which no identity on the route declares` : `kizuna: auth accepts the role "${RoleMismatch<Value, Identities>}", which no identity on the route declares` : 'kizuna: this route needs an `auth`. Name the identity it requires, or `false` for a public route';
87
+ type TreeAuthMismatch<Node, Identities> = Node extends RouteDefinition ? AuthMismatch<Node, Identities> : Node extends object ? string extends keyof Node ? never : { [Key in keyof Node]: TreeAuthMismatch<Node[Key], Identities> }[keyof Node] : never;
88
+ type AuthMismatchShape<Node, Identities> = { [Key in keyof Node]: Node[Key] extends RouteDefinition ? [AuthMismatch<Node[Key], Identities>] extends [never] ? unknown : {
89
+ auth: AuthMismatch<Node[Key], Identities>;
90
+ } : Node[Key] extends Routes ? AuthMismatchShape<Node[Key], Identities> : unknown };
91
+ /**
92
+ * Reports routes whose `auth` is missing, or names a role or permission its
93
+ * identities do not declare. Intersect it with the inferred route tree
94
+ * (`defs: T & AuthCheck<T, Identities>`): a sound tree gives `unknown`, leaving
95
+ * `T` untouched, and anything else resolves the offending `auth` to a message.
96
+ *
97
+ * An instance with no identities has nothing to state, so the check is off.
98
+ */
99
+ type AuthCheck<Tree, Identities> = [Identities] extends [Record<string, never>] ? unknown : [TreeAuthMismatch<Tree, Identities>] extends [never] ? unknown : AuthMismatchShape<Tree, Identities>;
100
+ /**
101
+ * The {@link AuthCheck} of one route, for `k.route`.
102
+ */
103
+ type RouteAuthCheck<Route, Identities> = [Identities] extends [Record<string, never>] ? unknown : [AuthMismatch<Route, Identities>] extends [never] ? unknown : {
104
+ auth: AuthMismatch<Route, Identities>;
105
+ };
106
+ //#endregion
107
+ //#region src/group-routes.d.ts
108
+ /**
109
+ * Routes from `k.routes`, carrying their group's path, `''` for none.
110
+ */
111
+ type DeclaredRoutes<T, Path extends string> = T & {
112
+ readonly [ROUTES_GROUP]?: Path;
113
+ };
114
+ /**
115
+ * Declare a tree of routes into one group.
116
+ */
117
+ type DeclareRoutes<Path extends string, GroupPaths extends string, Names extends string, Identities> = <const T extends AuthoredRoutes<GroupPaths, Names>>(routes: T & PathParamsCheck<T> & AuthCheck<T, Identities>) => DeclaredRoutes<T, Path>;
118
+ /**
119
+ * The groups nested under one.
120
+ */
121
+ type NestedOf<Options> = Options extends {
122
+ groups: infer Nested;
123
+ } ? Nested : {};
124
+ /**
125
+ * A group on `k.routes`: callable, and indexable by its nested groups.
126
+ */
127
+ type GroupAccessor<Options, Path extends string, GroupPaths extends string, Names extends string, Identities> = DeclareRoutes<Path, GroupPaths, Names, Identities> & { readonly [Key in Extract<keyof NestedOf<Options>, string>]: GroupAccessor<NestedOf<Options>[Key], `${Path}.${Key}`, GroupPaths, Names, Identities> };
128
+ /**
129
+ * `k.routes`: callable for routes in no group, and indexable by group.
130
+ */
131
+ type GroupRoutes<Declared, GroupPaths extends string, Names extends string, Identities> = DeclareRoutes<'', GroupPaths, Names, Identities> & { readonly [Key in Extract<keyof Declared, string>]: GroupAccessor<Declared[Key], Key, GroupPaths, Names, Identities> };
132
+ /**
133
+ * A tree, nested at its group's path.
134
+ */
135
+ type NestAt<Path extends string, T> = Path extends '' ? T : Path extends `${infer Head}.${infer Rest}` ? { [Key in Head]: NestAt<Rest, T> } : { [Key in Path]: T };
136
+ type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends ((value: infer Intersection) => void) ? Intersection : never;
137
+ type GroupOf<T> = T extends {
138
+ readonly [ROUTES_GROUP]?: infer Path extends string;
139
+ } ? (string extends Path ? '' : Path) : '';
140
+ /**
141
+ * The route tree `defineConfig` builds from its list.
142
+ */
143
+ type AssembledRoutes<List extends readonly unknown[]> = [List[number]] extends [never] ? Record<string, never> : UnionToIntersection<{ [Index in keyof List]: NestAt<GroupOf<List[Index]>, Omit<List[Index], typeof ROUTES_GROUP>> }[number]> extends infer Tree extends Routes ? Tree : Routes;
144
+ //#endregion
50
145
  //#region src/coded-issue.d.ts
51
146
  /**
52
147
  * A validation issue carrying a custom machine-readable {@link code}.
@@ -209,83 +304,11 @@ interface IdentityFactories<HandlerContext, RequestContext, GuardSchema> {
209
304
  custom<ContextSchema extends z.ZodType | undefined = undefined, RolesType extends Roles | undefined = undefined, ParamsSchema extends z.ZodType | undefined = undefined>(config: CustomConfig<ContextSchema, RolesType, ParamsSchema>): IdentityBuilder<Identity<ContextSchema, RolesType, NoCredential, ParamsSchema>, HandlerContext, RequestContext, GuardSchema>;
210
305
  }
211
306
  //#endregion
212
- //#region src/auth-check.d.ts
213
- /**
214
- * The role names an identity accepts, or `never` when it declares none.
215
- */
216
- type AcceptedRolesOf$1<Identities, Name extends string> = Name extends keyof Identities ? [RoleNamesOf<RolesOf<Identities[Name]>>] extends [never] ? never : RoleNamesOf<RolesOf<Identities[Name]>> : never;
217
- /**
218
- * The identity names one `auth` value requires.
219
- */
220
- type NamesIn<Value> = Value extends string ? Value : Value extends readonly (infer Name extends string)[] ? Name : Value extends {
221
- identity: infer Identity;
222
- } ? Identity extends string ? Identity : Identity extends readonly (infer Name extends string)[] ? Name : never : never;
223
- type RoleMismatch<Value, Identities> = Value extends {
224
- roles: infer Declared;
225
- } ? Exclude<Declared extends readonly (infer Role)[] ? Role : Declared, AcceptedRolesOf$1<Identities, NamesIn<Value>>> & string : never;
226
- /**
227
- * The verbs every identity on the route declares for one resource.
228
- */
229
- type VerbsFor<Identities, Names extends string, Resource extends string> = CatalogsOf<Identities, Names> extends infer Catalog ? Catalog extends Record<string, readonly string[]> ? Resource extends keyof Catalog ? Catalog[Resource][number] : never : never : never;
230
- type CatalogsOf<Identities, Names extends string> = Names extends keyof Identities ? CatalogOf<RolesOf<Identities[Names]>> : never;
231
- type RequiresMismatch<Value, Identities> = Value extends {
232
- requires: infer Declared;
233
- } ? { [Resource in keyof Declared & string]: Declared[Resource] extends readonly (infer Verb extends string)[] ? Verb extends VerbsFor<Identities, NamesIn<Value>, Resource> ? never : `${Resource}:${Verb}` : never }[keyof Declared & string] : never;
234
- /**
235
- * What is wrong with one route's `auth`, as a message, or `never` when it is
236
- * sound.
237
- */
238
- type AuthMismatch<Route, Identities> = Route extends {
239
- auth: infer Value;
240
- } ? [RoleMismatch<Value, Identities>] extends [never] ? [RequiresMismatch<Value, Identities>] extends [never] ? never : `kizuna: auth requires "${RequiresMismatch<Value, Identities>}", which no identity on the route declares` : `kizuna: auth accepts the role "${RoleMismatch<Value, Identities>}", which no identity on the route declares` : 'kizuna: this route needs an `auth`. Name the identity it requires, or `false` for a public route';
241
- type TreeAuthMismatch<Node, Identities> = Node extends RouteDefinition ? AuthMismatch<Node, Identities> : Node extends object ? string extends keyof Node ? never : { [Key in keyof Node]: TreeAuthMismatch<Node[Key], Identities> }[keyof Node] : never;
242
- type AuthMismatchShape<Node, Identities> = { [Key in keyof Node]: Node[Key] extends RouteDefinition ? [AuthMismatch<Node[Key], Identities>] extends [never] ? unknown : {
243
- auth: AuthMismatch<Node[Key], Identities>;
244
- } : Node[Key] extends Routes ? AuthMismatchShape<Node[Key], Identities> : unknown };
245
- /**
246
- * Reports routes whose `auth` is missing, or names a role or permission its
247
- * identities do not declare. Intersect it with the inferred route tree
248
- * (`defs: T & AuthCheck<T, Identities>`): a sound tree gives `unknown`, leaving
249
- * `T` untouched, and anything else resolves the offending `auth` to a message.
250
- *
251
- * An instance with no identities has nothing to state, so the check is off.
252
- */
253
- type AuthCheck<Tree, Identities> = [Identities] extends [Record<string, never>] ? unknown : [TreeAuthMismatch<Tree, Identities>] extends [never] ? unknown : AuthMismatchShape<Tree, Identities>;
254
- /**
255
- * The {@link AuthCheck} of one route, for `k.route`.
256
- */
257
- type RouteAuthCheck<Route, Identities> = [Identities] extends [Record<string, never>] ? unknown : [AuthMismatch<Route, Identities>] extends [never] ? unknown : {
258
- auth: AuthMismatch<Route, Identities>;
259
- };
260
- //#endregion
261
- //#region src/route.d.ts
262
- /**
263
- * A route and the handler that answers it. The handler is stored without its
264
- * argument types, so a config that lists routes never depends on what a handler
265
- * reads back off that config.
266
- */
267
- type RouteWithHandler<Definition extends AuthoredRouteDefinition> = Definition & {
268
- readonly [HANDLER]: RouteHandlerFunction;
269
- };
270
- /**
271
- * What `k.route` returns: the route itself, and the `handler` that answers it.
272
- * A route nothing serves, one a generator or a client reads, needs no handler.
273
- */
274
- type RouteBuilder<Definition extends AuthoredRouteDefinition, HandlerContext = unknown> = Definition & RouteHandlerStep<Definition, HandlerContext>;
275
- interface RouteHandlerStep<Definition extends AuthoredRouteDefinition, HandlerContext> {
276
- /**
277
- * The handler that answers this route. `body`, `params`, `query` and
278
- * `headers` are typed from the route, and the return is checked against its
279
- * `responses`.
280
- */
281
- handler(fn: RouteHandler<Definition, HandlerContext>): RouteWithHandler<Definition>;
282
- }
283
- //#endregion
284
307
  //#region src/job.d.ts
285
308
  /**
286
309
  * A job's handler, typed against the job it answers.
287
310
  */
288
- type JobHandlerFor<Definition extends AuthoredJobDefinition> = (args: JobHandlerArgs<Definition>) => Promise<JobHandlerReturn<Definition> | JobVoidReturn<Definition>> | JobHandlerReturn<Definition> | JobVoidReturn<Definition>;
311
+ type JobHandlerFor<Definition extends AuthoredJobDefinition, HandlerContext = unknown> = (args: JobHandlerArgs<Definition> & HandlerContext) => Promise<JobHandlerReturn<Definition> | JobVoidReturn<Definition>> | JobHandlerReturn<Definition> | JobVoidReturn<Definition>;
289
312
  /**
290
313
  * A job and the handler that runs it.
291
314
  */
@@ -296,106 +319,16 @@ type JobWithHandler<Definition extends AuthoredJobDefinition> = Definition & {
296
319
  * What `k.job` returns: the job itself, and the `handler` that runs it. A job
297
320
  * nothing runs, one a generator reads, needs no handler.
298
321
  */
299
- type JobBuilder<Definition extends AuthoredJobDefinition> = Definition & JobHandlerStep<Definition>;
300
- interface JobHandlerStep<Definition extends AuthoredJobDefinition> {
322
+ type JobBuilder<Definition extends AuthoredJobDefinition, HandlerContext = unknown> = Definition & JobHandlerStep<Definition, HandlerContext>;
323
+ interface JobHandlerStep<Definition extends AuthoredJobDefinition, HandlerContext> {
301
324
  /**
302
325
  * The handler that runs this job. `input` is typed from the job's schema,
303
- * and the return is checked against its `result`.
326
+ * `plugins` from the config, and the return is checked against its
327
+ * `result`.
304
328
  */
305
- handler(fn: JobHandlerFor<Definition>): JobWithHandler<Definition>;
329
+ handler(fn: JobHandlerFor<Definition, HandlerContext>): JobWithHandler<Definition>;
306
330
  }
307
331
  //#endregion
308
- //#region src/configured.d.ts
309
- /**
310
- * What one API is made of, written by `kizuna generate` and handed to
311
- * `new Kizuna<Config>()`. Everything a handler receives beyond its own inputs,
312
- * and every name kizuna checks a route against, is read from it.
313
- *
314
- * @example
315
- * ```ts
316
- * // src/kizuna.types.ts, generated
317
- * export interface Config {
318
- * adapter: ReturnType<typeof expressAdapter>;
319
- * tags: typeof tags;
320
- * auth: { identities: { user: typeof user } };
321
- * jobs: typeof jobs;
322
- * }
323
- * ```
324
- */
325
- interface KizunaConfigShape {
326
- adapter?: unknown;
327
- tags?: unknown;
328
- auth?: {
329
- identities?: unknown;
330
- guardSchema?: unknown;
331
- };
332
- requestContext?: unknown;
333
- validation?: {
334
- issueCodes?: string;
335
- };
336
- jobs?: unknown;
337
- plugins?: unknown;
338
- }
339
- /**
340
- * One job, as a handler reaches it.
341
- */
342
- interface JobFnOf<Definition extends AuthoredJobDefinition> {
343
- /**
344
- * Run the job now and resolve to what its handler returned.
345
- */
346
- run: Definition extends {
347
- input: z.ZodType;
348
- } ? (input: z.input<Definition['input']>) => Promise<JobHandlerReturn<Definition>> : () => Promise<JobHandlerReturn<Definition>>;
349
- /**
350
- * Put the job in line and answer without waiting for it.
351
- */
352
- queue: Definition extends {
353
- input: z.ZodType;
354
- } ? (message: {
355
- input: z.input<Definition['input']>;
356
- } & JobQueueOptions) => Promise<void> : (message?: JobQueueOptions) => Promise<void>;
357
- }
358
- /**
359
- * A tree of jobs, as a handler reaches them.
360
- */
361
- type JobsOfTree<Tree> = { [Key in keyof Tree]: Tree[Key] extends {
362
- definition: infer Definition extends AuthoredJobDefinition;
363
- } ? JobFnOf<Definition> : JobsOfTree<Tree[Key]> };
364
- type ConfiguredTags<Config> = Config extends {
365
- tags: TagSet<infer Tags extends Record<string, TagOptions>>;
366
- } ? Tags : Record<string, never>;
367
- type ConfiguredCodes<Config> = Config extends {
368
- validation: {
369
- issueCodes: infer Codes extends string;
370
- };
371
- } ? Codes : never;
372
- type ConfiguredIdentities<Config> = Config extends {
373
- auth: {
374
- identities: infer Identities extends Record<string, SecurityScheme>;
375
- };
376
- } ? Identities : Record<string, never>;
377
- type ConfiguredRequestContextSchemas<Config> = Config extends {
378
- requestContext: infer Declarations extends Record<string, RequestContextSchema>;
379
- } ? Declarations : Record<string, never>;
380
- type ConfiguredGuardSchema<Config> = Config extends {
381
- auth: {
382
- guardSchema: infer Schema extends z.ZodType;
383
- };
384
- } ? Schema : undefined;
385
- type ConfiguredAdapterValue<Config> = Config extends {
386
- adapter: infer Adapter extends AnyAdapter;
387
- } ? Adapter : undefined;
388
- type ConfiguredJobs<Config> = Config extends {
389
- jobs: infer Tree;
390
- } ? {
391
- jobs: JobsOfTree<Tree>;
392
- } : {};
393
- type ConfiguredPlugins<Config> = Config extends {
394
- plugins: infer Plugins extends PluginList;
395
- } ? PluginArgs<PluginsBySlug<Plugins>> : {};
396
- type ConfiguredAdapterContext<Config> = HandlerContextOf<ConfiguredAdapterValue<Config>>;
397
- type ConfiguredRequestContext<Config> = RequestContextValues<ConfiguredRequestContextSchemas<Config>>;
398
- //#endregion
399
332
  //#region src/kizuna.d.ts
400
333
  /**
401
334
  * What a route requires of its caller: an identity name, several of them for
@@ -430,7 +363,7 @@ type RouteAuthRule<Id extends string = string, Identities = Record<string, unkno
430
363
  * What a {@link Kizuna} instance declares.
431
364
  */
432
365
  interface KizunaSpec {
433
- tags: Record<string, TagOptions>;
366
+ groups: Record<string, GroupOptions | string>;
434
367
  codes: string;
435
368
  identities: Record<string, SecurityScheme>;
436
369
  requestContext: Record<string, RequestContextSchema>;
@@ -439,9 +372,9 @@ interface KizunaSpec {
439
372
  config: unknown;
440
373
  }
441
374
  /**
442
- * The tag names declared on a spec, e.g. `'health' | 'users'`.
375
+ * The dotted group paths a spec declares.
443
376
  */
444
- type TagNamesOf<Spec extends KizunaSpec> = Extract<keyof Spec['tags'], string>;
377
+ type GroupNamesOf<Spec extends KizunaSpec> = GroupPaths<Spec['groups']>;
445
378
  /**
446
379
  * The identity names declared on a spec, e.g. `'user' | 'member'`.
447
380
  */
@@ -455,7 +388,7 @@ interface K<Spec extends KizunaSpec = KizunaSpec> {
455
388
  * `query` and `headers` are typed from the route, and the return is checked
456
389
  * against its `responses`.
457
390
  *
458
- * Group routes with `k.routes`, which takes the routes this returns.
391
+ * File routes into a group with `k.routes`.
459
392
  *
460
393
  * @example
461
394
  * export const createUser = k
@@ -474,13 +407,18 @@ interface K<Spec extends KizunaSpec = KizunaSpec> {
474
407
  * body: await db.users.create(body.name),
475
408
  * }));
476
409
  */
477
- route<const Definition extends AuthoredRouteDefinition<TagNamesOf<Spec>, IdentityNamesOf<Spec>>>(definition: Definition & RoutePathParamsCheck<Definition> & RouteAuthCheck<Definition, Spec['identities']>): RouteBuilder<Definition & RouteGuardBrandOf<Definition, GuardOutput<Spec['guardSchema']>, GuardBody<Spec['guardSchema']>>, HandlerContextFor<Spec, Definition>>;
410
+ route<const Definition extends AuthoredRouteDefinition<GroupNamesOf<Spec>, IdentityNamesOf<Spec>>>(definition: Definition & RoutePathParamsCheck<Definition> & RouteAuthCheck<Definition, Spec['identities']> & RouteHiddenToolCheck<Definition>): RouteBuilder<Definition & RouteGuardBrandOf<Definition, GuardOutput<Spec['guardSchema']>, GuardBody<Spec['guardSchema']>>, HandlerContextFor<Spec, Definition>>;
478
411
  /**
479
- * Define a group of routes. Pass a tag (one of the keys from `k.tags`)
480
- * to group them in the OpenAPI document, or omit it for an untagged group.
412
+ * Declare routes into a group. Call `k.routes` itself for routes in no
413
+ * group.
414
+ *
415
+ * @example
416
+ * export const memberRoutes = k.routes.workspace.members({
417
+ * listMembers,
418
+ * removeMember,
419
+ * });
481
420
  */
482
- routes<const T extends AuthoredRoutes<TagNamesOf<Spec>, IdentityNamesOf<Spec>>>(tag: TagNamesOf<Spec>, defs: T & PathParamsCheck<T> & AuthCheck<T, Spec['identities']>): T;
483
- routes<const T extends AuthoredRoutes<string, IdentityNamesOf<Spec>>>(defs: T & PathParamsCheck<T> & AuthCheck<T, Spec['identities']>): T;
421
+ routes: GroupRoutes<Spec['groups'], GroupNamesOf<Spec>, IdentityNamesOf<Spec>, Spec['identities']>;
484
422
  /**
485
423
  * Declare one job and the handler that runs it. `input` is typed from the
486
424
  * job's schema, and the return is checked against its `result`.
@@ -500,7 +438,7 @@ interface K<Spec extends KizunaSpec = KizunaSpec> {
500
438
  * },
501
439
  * }));
502
440
  */
503
- job<const Definition extends AuthoredJobDefinition>(definition: Definition): JobBuilder<Definition>;
441
+ job<const Definition extends AuthoredJobDefinition>(definition: Definition): JobBuilder<Definition, JobHandlerContextFor<Spec>>;
504
442
  /**
505
443
  * Declare scheduled jobs. Pass the identity every job requires, the one
506
444
  * credential your scheduler sends, then the jobs themselves.
@@ -551,10 +489,19 @@ interface K<Spec extends KizunaSpec = KizunaSpec> {
551
489
  * });
552
490
  */
553
491
  /**
554
- * Declare the OpenAPI tags routes are grouped under. `k.routes` takes one of
555
- * these names.
492
+ * Declare the groups routes are filed under.
493
+ *
494
+ * @example
495
+ * export const groups = k.groups({
496
+ * workspace: {
497
+ * title: 'Workspace',
498
+ * groups: {
499
+ * members: 'Members',
500
+ * },
501
+ * },
502
+ * });
556
503
  */
557
- tags: typeof createTags;
504
+ groups: typeof createGroups;
558
505
  identity: IdentityFactories<ConfiguredAdapterContext<Spec['config']>, ConfiguredRequestContext<Spec['config']>, ConfiguredGuardSchema<Spec['config']>>;
559
506
  /**
560
507
  * Declare a request-scoped value and the resolver that fills it. It runs on
@@ -597,7 +544,7 @@ interface K<Spec extends KizunaSpec = KizunaSpec> {
597
544
  * is checked against.
598
545
  */
599
546
  type SpecOf<Config> = {
600
- tags: ConfiguredTags<Config>;
547
+ groups: ConfiguredGroups<Config>;
601
548
  codes: ConfiguredCodes<Config>;
602
549
  identities: ConfiguredIdentities<Config>;
603
550
  requestContext: ConfiguredRequestContextSchemas<Config>;
@@ -611,12 +558,19 @@ type SpecOf<Config> = {
611
558
  * handler.
612
559
  */
613
560
  type HandlerContextFor<Spec extends KizunaSpec, Definition> = AuthContextOf<Definition, Spec['identities']> & ConfiguredRequestContext<Spec['config']> & ConfiguredJobs<Spec['config']> & ConfiguredPlugins<Spec['config']> & ConfiguredAdapterContext<Spec['config']>;
561
+ /**
562
+ * What every job's handler receives beyond its input, typed: the installed
563
+ * plugins' exports. `jobs` reaches it at runtime too, but stays untyped here,
564
+ * since the generated `Config` holds `typeof jobs` and a job typed from it would
565
+ * depend on itself.
566
+ */
567
+ type JobHandlerContextFor<Spec extends KizunaSpec> = ConfiguredPlugins<Spec['config']>;
614
568
  /**
615
569
  * The authoring surface for one API. Its type parameter is the `Config` that
616
570
  * `kizuna generate` writes, which is what every name on `k` is checked against
617
571
  * and what types everything a handler receives.
618
572
  *
619
- * `k.route` declares a route with its handler, `k.routes` groups them, and
573
+ * `k.route` declares a route with its handler, `k.routes` files them into groups, and
620
574
  * `k.job` and `k.jobs` do the same for jobs.
621
575
  * `defineConfig` assembles them.
622
576
  *
@@ -631,6 +585,11 @@ declare class Kizuna<Config extends KizunaConfigShape = Record<string, never>> i
631
585
  * the one type rather than inlining it.
632
586
  */
633
587
  static readonly model: <T extends z.ZodType>(options: ModelOptions<T>) => T;
588
+ /**
589
+ * Brand a schema, so the server and every generated client type its values
590
+ * as that brand.
591
+ */
592
+ static readonly brand: <Brand extends string, T extends BrandableSchema>(brand: Brand, schema: T) => z.core.$ZodBranded<T, Brand>;
634
593
  /**
635
594
  * Declare the permissions callers hold, as a catalog of resources and the
636
595
  * verbs each allows.
@@ -640,7 +599,7 @@ declare class Kizuna<Config extends KizunaConfigShape = Record<string, never>> i
640
599
  * Declare the roles callers hold, as names or from a permission catalog.
641
600
  */
642
601
  static readonly roles: typeof createRoles;
643
- readonly tags: K<SpecOf<Config>>['tags'];
602
+ readonly groups: K<SpecOf<Config>>['groups'];
644
603
  readonly route: K<SpecOf<Config>>['route'];
645
604
  readonly routes: K<SpecOf<Config>>['routes'];
646
605
  readonly job: K<SpecOf<Config>>['job'];
@@ -745,9 +704,9 @@ declare const failedJobs: (result: DispatchResult) => string[];
745
704
  //#endregion
746
705
  //#region src/tool-records.d.ts
747
706
  /**
748
- * How far along one tool call is.
707
+ * How far along one tool call is. `needs-approval` waits for the person.
749
708
  */
750
- type ToolCallState = 'running' | 'done' | 'failed';
709
+ type ToolCallState = 'running' | 'needs-approval' | 'done' | 'failed';
751
710
  /**
752
711
  * The shape {@link readToolCalls} reads: whatever a stream hands back, as long
753
712
  * as each message names its event.
@@ -834,54 +793,12 @@ interface ApiImplementations {
834
793
  onJobError?: JobErrorHandler;
835
794
  }
836
795
  //#endregion
837
- //#region src/config.d.ts
838
- /**
839
- * A client generated from a config, created by its generator's own factory so
840
- * the options are typed where the generator lives.
841
- *
842
- * @example
843
- * import { swiftClient } from '@kizunajs/swift';
844
- */
845
- interface ClientTarget {
846
- /**
847
- * The generator that produced this target, for messages and reporting.
848
- */
849
- readonly kind: string;
850
- /**
851
- * Path the generated file is written to.
852
- */
853
- readonly output: string;
854
- /**
855
- * Renders the file this target writes.
856
- */
857
- readonly generate: (contract: ApiDefinition) => string;
858
- }
859
- /**
860
- * What `kizuna.config.ts` default-exports: the api its config assembles, and
861
- * what is generated from it.
862
- */
863
- interface ApiEntry {
864
- api: ApiDefinition;
865
- clients?: readonly ClientTarget[];
866
- /**
867
- * Where `kizuna generate` writes the `Config`.
868
- */
869
- typescript?: {
870
- outputFile?: string;
871
- };
872
- }
873
- /**
874
- * The config a `kizuna.config.ts` module default-exports. A repository serving
875
- * several APIs writes a config file for each.
876
- */
877
- declare const apiEntries: (module: Record<string, unknown>) => [string, ApiEntry][];
878
- //#endregion
879
796
  //#region src/define-config.d.ts
880
797
  /**
881
798
  * What one API is made of. Everything kizuna knows about an API is written
882
799
  * here: what it declares, and what serves it.
883
800
  */
884
- type KizunaConfigInput<R extends Routes, J extends Jobs, P extends PluginList, Tags extends Record<string, TagOptions>, Codes extends string, Identities extends Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema>, GuardSchema extends z.ZodType | undefined, AdapterValue extends AnyAdapter | undefined> = {
801
+ type KizunaConfigInput<R extends readonly Routes[], J extends Jobs, P extends PluginList, Groups extends Record<string, GroupOptions | string>, Codes extends string, Identities extends Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema>, GuardSchema extends z.ZodType | undefined, AdapterValue extends AnyAdapter | undefined> = {
885
802
  /**
886
803
  * The framework this API is served on, as a value. Its handler context
887
804
  * reaches every handler, and the api it returns mounts onto that
@@ -892,8 +809,10 @@ type KizunaConfigInput<R extends Routes, J extends Jobs, P extends PluginList, T
892
809
  */
893
810
  adapter?: AdapterValue;
894
811
  /**
895
- * The route groups this API answers, as `k.routes` returned them. Omit it
896
- * while setting up, before there is a route to name.
812
+ * What `k.routes` returned, as a list in any order.
813
+ *
814
+ * @example
815
+ * routes: [userRoutes, memberRoutes, healthRoutes],
897
816
  */
898
817
  routes?: R;
899
818
  jobs?: J;
@@ -905,7 +824,10 @@ type KizunaConfigInput<R extends Routes, J extends Jobs, P extends PluginList, T
905
824
  * plugins: [mcpPlugin({ name: 'workspace' }), openApiPlugin({ info })],
906
825
  */
907
826
  plugins?: P;
908
- tags?: TagSet<Tags>;
827
+ /**
828
+ * The groups from `k.groups`.
829
+ */
830
+ groups?: GroupSet<Groups>;
909
831
  /**
910
832
  * Who may call this API: the identities a route's `auth` names, and the
911
833
  * body their guards refuse with.
@@ -944,13 +866,6 @@ type KizunaConfigInput<R extends Routes, J extends Jobs, P extends PluginList, T
944
866
  */
945
867
  issueCodes?: readonly Codes[];
946
868
  };
947
- /**
948
- * How this deployment runs the jobs it declares: where the two endpoints
949
- * sit, what carries queued work out of the process, and where a failure is
950
- * reported. The jobs themselves are declared with `k.jobs` and go under
951
- * `jobs`.
952
- */
953
- jobRunner?: JobRunnerConfig;
954
869
  /**
955
870
  * What `kizuna generate` writes the `Config` to.
956
871
  *
@@ -973,13 +888,36 @@ type KizunaConfigInput<R extends Routes, J extends Jobs, P extends PluginList, T
973
888
  * }),
974
889
  * ],
975
890
  */
976
- clients?: readonly ClientTarget[];
891
+ clients?: readonly GeneratedFile[];
892
+ /**
893
+ * What else `kizuna diff` treats as breaking.
894
+ *
895
+ * @example
896
+ * diff: {
897
+ * dottedKeys: true,
898
+ * }
899
+ */
900
+ diff?: DiffSettings;
901
+ } & JobRunnerInput<J>;
902
+ /**
903
+ * `jobRunner`, required once `jobs` declares one.
904
+ */
905
+ type JobRunnerInput<J extends Jobs> = string extends keyof J ? {
906
+ jobRunner?: JobRunnerConfig;
907
+ } : {
908
+ /**
909
+ * How this deployment runs the jobs it declares: over HTTP or in
910
+ * process, what carries queued work out of the process, and where a
911
+ * failure is reported. The jobs themselves are declared with
912
+ * `k.jobs` and go under `jobs`.
913
+ */
914
+ jobRunner: JobRunnerConfig;
977
915
  };
978
916
  /**
979
917
  * The api `defineConfig` assembles: the routes it declares, and the `mount`
980
918
  * that serves it.
981
919
  */
982
- type ConfiguredApi<R extends Routes, J extends Jobs, P extends PluginList, Tags extends Record<string, TagOptions>, Codes extends string, Identities extends Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema>, GuardSchema extends z.ZodType | undefined, AdapterValue extends AnyAdapter | undefined> = Api<ApiDefinition<RoutesWithHandlerContext<R, Identities, RequestContext, PluginArgs<PluginsBySlug<P>> & JobsArg<J>, GuardOutput<GuardSchema>, GuardBody<GuardSchema>>, Tags, Codes, Identities, RequestContext, PluginsBySlug<P>, J, GuardSchema>, AdapterValue>;
920
+ type ConfiguredApi<R extends readonly Routes[], J extends Jobs, P extends PluginList, Groups extends Record<string, GroupOptions | string>, Codes extends string, Identities extends Record<string, SecurityScheme>, RequestContext extends Record<string, RequestContextSchema>, GuardSchema extends z.ZodType | undefined, AdapterValue extends AnyAdapter | undefined> = Api<ApiDefinition<RoutesWithHandlerContext<AssembledRoutes<R>, Identities, RequestContext, PluginArgs<PluginsBySlug<P>> & JobsArg<J>, GuardOutput<GuardSchema>, GuardBody<GuardSchema>>, Groups, Codes, Identities, RequestContext, PluginsBySlug<P>, J, GuardSchema>, AdapterValue>;
983
921
  /**
984
922
  * Everything kizuna knows about one API, written in `kizuna.config.ts`. Every
985
923
  * route's `auth` resolves onto its `security`, `roles` and `requires`, the
@@ -997,12 +935,14 @@ type ConfiguredApi<R extends Routes, J extends Jobs, P extends PluginList, Tags
997
935
  * },
998
936
  * });
999
937
  */
1000
- declare const defineConfig: <const R extends Routes = Record<string, never>, const J extends Jobs = Record<string, never>, const P extends PluginList = readonly [], const Tags extends Record<string, TagOptions> = Record<string, never>, const Codes extends string = never, const Identities extends Record<string, SecurityScheme> = Record<string, never>, const RequestContext extends Record<string, RequestContextSchema> = Record<string, never>, GuardSchema extends z.ZodType | undefined = undefined, const AdapterValue extends AnyAdapter | undefined = undefined>(options: KizunaConfigInput<R, J, P, Tags, Codes, Identities, RequestContext, GuardSchema, AdapterValue>) => {
1001
- api: ConfiguredApi<R, J, P, Tags, Codes, Identities, RequestContext, GuardSchema, AdapterValue>;
1002
- clients: readonly ClientTarget[];
938
+ declare const defineConfig: <const R extends readonly Routes[] = readonly [], const J extends Jobs = Record<string, never>, const P extends PluginList = readonly [], const Groups extends Record<string, GroupOptions | string> = {}, const Codes extends string = never, const Identities extends Record<string, SecurityScheme> = Record<string, never>, const RequestContext extends Record<string, RequestContextSchema> = Record<string, never>, GuardSchema extends z.ZodType | undefined = undefined, const AdapterValue extends AnyAdapter | undefined = undefined>(options: KizunaConfigInput<R, J, P, Groups, Codes, Identities, RequestContext, GuardSchema, AdapterValue>) => {
939
+ api: ConfiguredApi<R, J, P, Groups, Codes, Identities, RequestContext, GuardSchema, AdapterValue>;
940
+ clients: readonly GeneratedFile[];
941
+ generators: readonly GeneratedFile[];
1003
942
  typescript: {
1004
943
  outputFile?: string;
1005
944
  } | undefined;
945
+ diff: DiffSettings | undefined;
1006
946
  };
1007
947
  //#endregion
1008
- export { AUTO_GUARD_BRAND, AUTO_GUARD_WRITTEN_BRAND, AUTO_RESPONSES_BRAND, type AnyPlugin, type Api, type ApiDefinition, type ApiEntry, type ApiImplementations, type ApiKeyCredential, type ApiPlugins, type ApiPluginsOf, type AuthCheck, type AuthContextOf, type AuthoredJobs, type AuthoredRouteDefinition, type AuthoredRoutes, type AutoResponsesBrand, type BasicCredential, type BearerCredential, type BrandedHandlerContext, type BuiltinIssueCode, type CachePolicy, type CatalogOf, type ClientTarget, type CodedIssue, type CompiledJob, type CompiledJobs, type ConfiguredApi, type ContextFromAuth, type ContextOf, type Credential, type CredentialOf, DECLARATION, type DeclarationKind, DispatchFailedSchema, type DispatchOptions, type DispatchOutcome, type DispatchResult, DispatchResultSchema, EVENT_STREAM_MEDIA_TYPE, type ExtractPathParams, type FlattenedJob, GUARD, type GrantNamesOf, type GrantsOf, type GuardAnswer, type GuardBody, type GuardFor, type GuardHoldings, type GuardOutput, type GuardReturn, type GuardSchemaOf, type GuardStatus, type GuardSuccess, HANDLER_CONTEXT_BRAND, type HandlerArgs, type HandlerContextBrand, type HandlerReturn, type HasPathParams, type Identity, type IdentityBuilder, type IdentityFactories, type IdentityNamesOf, type IdentityParamsOf, type IdentityRole, type IdentityWithGuard, type JobBuilder, type JobDefinition, type JobDescriptor, JobDispatchError, type JobErrorHandler, type JobFn, type JobFnByKey, type JobFnOf, type JobHandler, type JobHandlerArgs, type JobHandlerFor, type JobHandlerReturn, type JobHandlers, JobInputError, type JobMessage, type JobQueueArgs, type JobQueueOptions, type JobResponses, type JobRunArgs, type JobRunner, type JobRunnerOptions, type JobSchedule, type JobTransport, type JobTransportDefinition, type JobTransportSupports, type JobWithHandler, type JobWorker, type JobWorkerContext, type Jobs, type JobsArg, type JobsConfig, type JobsOf, type JobsOfTree, type K, Kizuna, type KizunaConfigInput, type KizunaConfigShape, type KizunaSpec, METHODS, type Method, type ModelOptions, type NoCredential, type NoJobs, type NormalizeTags, type OAuthFlow, type OAuthFlows, type OpenApiSecuritySchemeObject, type ParsedCron, type PathParamName, type PermissionCatalog, type PermissionName, type PermissionSet, type Permissions, type PluginArgs, type PluginDeclaration, type PluginDefinition, type PluginExportValues, type PluginExportsOf, type PluginList, type PluginPropsOf, type PluginRoutes, type PluginRoutesOf, type PluginsBySlug, type ProblemDetails, type ProtectedResourceConfig, type ProtectedResourceMetadata, RESOLVER, type RegisteredIssue, type RequestContextBuilder, type RequestContextHeaderInputs, type RequestContextHeaderValues, type RequestContextOf, type RequestContextSchema, type RequestContextWithHandler, type RequiredPermissions, type ResponseContentType, type ResponseDefinition, ResponseError, type RoleDefinition, type RoleNamesOf, type RoleOf, type Roles, type RolesOf, type RouteAuth, type RouteAuthCheck, type RouteAuthRule, type RouteAuthValue, type RouteBuilder, type RouteDefinition, type RouteHandlerFunction, type RoutePath, type RouteToolOptions, type RouteWithHandler, type Routes, type RoutesOf, type RoutesWithHandlerContext, STATUS_TITLES, type ScheduledJob, type SchemeNameOf, type SchemesOf, type SecurityRequirement, type SecurityScheme, type StreamBody, type StreamBodyOf, type StreamChunk, type StreamComment, type StreamContext, type StreamDefinition, type StreamMessage, type StreamMessageOf, type StreamMode, type StreamResponseDefinition, type StreamWithTools, type StreamYield, type StripProblemEnvelope, type TagKeysOf, type TagNamesOf, type TagOptions, type TagSet, type ThrowableReturn, type ToolAt, type ToolCall, type ToolCallMessage, type ToolCallRecord, type ToolCallState, type ToolError, type ToolEvents, type ToolKeys, type ToolResult, type ValidationError, type ValidationErrorFor, type ValidationIssueCode, apiEntries, assertCanonicalResourceUri, assertValidSchedule, authorizationServerIssuer, buildPath, buildProtectedResourceMetadata, createJobRunner, createJobTransport, createPlugin, cron, declaredScopes, defineConfig, dispatchDueJobs, dispatchSucceeded, dueJobs, dueSchedules, expandStreamTools, failedJobs, firesBetween, flattenJobs, getHeaderValue, getStatusText, isCompiledJob, isJobDefinition, isNamedStream, isPermissions, isProblemDetails, isRoles, isRouteDefinition, isSecurityScheme, isStreamResponse, isValidationError, isZodSchema, jobAt, jobFnAt, nextRun, nextRuns, parseCron, parsePath, problemDetails, problemFromBody, readToolCalls, routeStreams, scheduleExpression, scheduleTimezone, soleStreamResponse, streamContentType, streamMode, streamStatuses, toolEvents };
948
+ export { AUTO_GUARD_BRAND, AUTO_GUARD_WRITTEN_BRAND, AUTO_RESPONSES_BRAND, type AnyPlugin, type Api, type ApiDefinition, type ApiEntry, type ApiImplementations, type ApiKeyCredential, type ApiPlugins, type ApiPluginsOf, type AssembledRoutes, type AuthCheck, type AuthContextOf, type AuthoredJobs, type AuthoredRouteDefinition, type AuthoredRoutes, type AutoResponsesBrand, type BasicCredential, type BearerCredential, type BrandedHandlerContext, type BuiltinIssueCode, type CachePolicy, type CatalogOf, type CodedIssue, type CompiledJob, type CompiledJobs, type ConfiguredApi, type ContextFromAuth, type ContextOf, type Credential, type CredentialOf, DECLARATION, type DeclarationKind, type DeclaredRoutes, type DiffSettings, DispatchFailedSchema, type DispatchOptions, type DispatchOutcome, type DispatchResult, DispatchResultSchema, EVENT_STREAM_MEDIA_TYPE, type ExtractPathParams, type FlattenedJob, GUARD, type GeneratedFile, type GrantNamesOf, type GrantsOf, type GroupNamesOf, type GroupOptions, type GroupPaths, type GroupPathsOf, type GroupSet, type GuardAnswer, type GuardBody, type GuardFor, type GuardHoldings, type GuardOutput, type GuardReturn, type GuardSchemaOf, type GuardStatus, type GuardSuccess, HANDLER_CONTEXT_BRAND, type HandlerArgs, type HandlerContextBrand, type HandlerReturn, type HasPathParams, type HttpJobsConfig, type Identity, type IdentityBuilder, type IdentityFactories, type IdentityNamesOf, type IdentityParamsOf, type IdentityRole, type IdentityWithGuard, type InProcessJobsConfig, type JobBuilder, type JobDefinition, type JobDescriptor, JobDispatchError, type JobErrorHandler, type JobFn, type JobFnByKey, type JobFnOf, type JobHandler, type JobHandlerArgs, type JobHandlerFor, type JobHandlerReturn, type JobHandlers, JobInputError, type JobMessage, type JobQueueArgs, type JobQueueOptions, type JobResponses, type JobRunArgs, type JobRunner, type JobRunnerOptions, type JobSchedule, type JobTransport, type JobTransportDefinition, type JobTransportSupports, type JobWithHandler, type JobWorker, type JobWorkerContext, type Jobs, type JobsArg, type JobsConfig, type JobsOf, type JobsOfTree, type K, Kizuna, type KizunaConfigInput, type KizunaConfigShape, type KizunaSpec, METHODS, type Method, type ModelOptions, type ModelToolCall, type NoCredential, type NoJobs, type OAuthFlow, type OAuthFlows, type OpenApiSecuritySchemeObject, type ParsedCron, type PathParamName, type PermissionCatalog, type PermissionName, type PermissionSet, type Permissions, type PluginApi, type PluginArgs, type PluginDeclaration, type PluginDefinition, type PluginExportValues, type PluginExportsOf, type PluginFactory, type PluginList, type PluginRoutes, type PluginRoutesOf, type PluginSetup, type PluginSetupContext, type PluginsBySlug, type ProblemDetails, type ProtectedResourceConfig, type ProtectedResourceMetadata, RESOLVER, ROUTES_GROUP, type RegisteredIssue, type RequestContextBuilder, type RequestContextHeaderInputs, type RequestContextHeaderValues, type RequestContextOf, type RequestContextSchema, type RequestContextWithHandler, type RequiredPermissions, type ResolvedGroup, type ResponseContentType, type ResponseDefinition, ResponseError, type RoleDefinition, type RoleNamesOf, type RoleOf, type Roles, type RolesOf, type RouteAuth, type RouteAuthCheck, type RouteAuthRule, type RouteAuthValue, type RouteBuilder, type RouteDefinition, type RouteHandlerFunction, type RoutePath, type RouteToolOptions, type RouteWithHandler, type Routes, type RoutesOf, type RoutesWithHandlerContext, STATUS_TITLES, type ScheduledJob, type SchemeNameOf, type SchemesOf, type SecurityRequirement, type SecurityScheme, type StreamBody, type StreamBodyOf, type StreamChunk, type StreamComment, type StreamContext, type StreamDefinition, type StreamMessage, type StreamMessageOf, type StreamMode, type StreamResponseDefinition, type StreamTools, type StreamWithTools, type StreamYield, type StripProblemEnvelope, type ThrowableReturn, type ToolAnswer, type ToolAt, type ToolCall, type ToolCallMessage, type ToolCallRecord, type ToolCallState, type ToolDefinition, type ToolError, type ToolEventYield, type ToolEvents, type ToolKeys, type ToolResult, type ToolRunCall, type ToolRunOptions, type ToolRunResult, type ValidationError, type ValidationErrorFor, type ValidationIssueCode, apiEntries, assertCanonicalResourceUri, assertValidSchedule, authorizationServerIssuer, buildPath, buildProtectedResourceMetadata, createJobRunner, cron, declaredScopes, defineConfig, defineJobTransport, definePlugin, dispatchDueJobs, dispatchSucceeded, dueJobs, dueSchedules, expandStreamTools, failedJobs, firesBetween, flattenJobs, getHeaderValue, getStatusText, isCompiledJob, isJobDefinition, isNamedStream, isPermissions, isProblemDetails, isRoles, isRouteDefinition, isSecurityScheme, isStreamResponse, isValidationError, isZodSchema, jobAt, jobFnAt, nextRun, nextRuns, parseCron, parsePath, problemDetails, problemFromBody, readToolCalls, routeStreams, scheduleExpression, scheduleTimezone, soleStreamResponse, streamContentType, streamMode, streamStatuses, toolEvents };