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
@@ -1,5 +1,6 @@
1
- import { PLUGIN_ROUTES_META_KEY, PLUGIN_SERVERS_META_KEY, type ApiPlugins } from './plugin.js';
2
- import type { Routes } from './types.js';
1
+ import type { z } from 'zod';
2
+ import { PLUGIN_ROUTES_META_KEY, PLUGIN_SERVERS_META_KEY, type PluginApi, type PluginDeclaration, type ResolvedPlugin } from './plugin.js';
3
+ import type { RoutePath, Routes } from './types.js';
3
4
 
4
5
  /**
5
6
  * The plugin routes `assembleApi` stashed on the api. Empty without plugins, so
@@ -34,24 +35,133 @@ export const pluginExportsOf = (api: unknown): Record<string, unknown> => {
34
35
  };
35
36
 
36
37
  /**
37
- * Run every plugin's `serve`. Deferred until the api object exists, because
38
- * `serve` receives it.
39
- */
40
- export const resolvePluginServers = (
41
- plugins: ApiPlugins | undefined,
42
- api: unknown
43
- ): Record<string, { router: Record<string, unknown>; exports?: unknown }> => {
44
- const resolved: Record<string, { router: Record<string, unknown>; exports?: unknown }> = {};
45
- for (const [pluginKey, declaration] of Object.entries(plugins ?? {})) {
46
- const served = declaration.serve(declaration.props as never, api) as {
47
- router: Record<string, unknown>;
48
- exports?: unknown;
49
- };
50
- for (const routeKey of Object.keys(declaration.routes)) {
51
- if (routeKey in served.router) continue;
52
- throw new Error(`Plugin '${pluginKey}' declares the route '${routeKey}' but its \`serve\` does not handle it.`);
38
+ * One issue as the app should read it: the field, and what's wrong with it.
39
+ */
40
+ export const describeIssue = (issue: z.core.$ZodIssue): string => {
41
+ const field = issue.path.map(String).join('.');
42
+ if (issue.code === 'invalid_type' && issue.message.endsWith('received undefined')) {
43
+ return `${field} is required`;
44
+ }
45
+ return field === '' ? issue.message : `${field}: ${issue.message}`;
46
+ };
47
+
48
+ /**
49
+ * A route's path under its plugin's base path. A route at `/` serves the base
50
+ * path itself, since `/webhooks` and `/webhooks/` are different paths.
51
+ */
52
+ const underBasePath = (basePath: string, path: string): RoutePath => (path === '/' ? basePath : `${basePath}${path}`) as RoutePath;
53
+
54
+ /**
55
+ * The base path a plugin's routes are served under: the app's, else the
56
+ * plugin's own. An app can only move a plugin that declares one.
57
+ */
58
+ const basePathOf = (declaration: PluginDeclaration): string | undefined => {
59
+ const { definition, slug } = declaration;
60
+ if (declaration.basePath !== undefined && definition.basePath === undefined) {
61
+ throw new Error(`[kizuna] Plugin '${slug}' declares no \`basePath\`, so its routes can't be moved. Remove \`basePath\`.`);
62
+ }
63
+ const basePath = declaration.basePath ?? definition.basePath;
64
+ if (basePath !== undefined && (!basePath.startsWith('/') || basePath.endsWith('/'))) {
65
+ throw new Error(
66
+ `[kizuna] Plugin '${slug}' has the base path '${basePath}'. A base path starts with \`/\` and doesn't end with one.`
67
+ );
68
+ }
69
+ return basePath;
70
+ };
71
+
72
+ /**
73
+ * Validate one installed plugin's options and run its `setup`.
74
+ */
75
+ const resolvePlugin = (declaration: PluginDeclaration, api: PluginApi): ResolvedPlugin => {
76
+ const { definition, slug } = declaration;
77
+ let options: unknown = undefined;
78
+ if (definition.options !== undefined) {
79
+ const parsed = definition.options.safeParse(declaration.input);
80
+ if (!parsed.success) {
81
+ throw new Error(`[kizuna] Plugin '${slug}' has invalid options: ${parsed.error.issues.map(describeIssue).join('; ')}`);
82
+ }
83
+ options = parsed.data;
84
+ }
85
+ const setup = definition.setup({
86
+ options: options as never,
87
+ api,
88
+ });
89
+ const basePath = basePathOf(declaration);
90
+ const routes = setup.routes ?? {};
91
+ return {
92
+ slug,
93
+ definedSlug: definition.slug,
94
+ options,
95
+ routes:
96
+ basePath === undefined
97
+ ? routes
98
+ : Object.fromEntries(
99
+ Object.entries(routes).map(([routeKey, route]) => [
100
+ routeKey,
101
+ {
102
+ ...route,
103
+ path: underBasePath(basePath, route.path),
104
+ },
105
+ ])
106
+ ),
107
+ exports: setup.exports,
108
+ generators: setup.generators ?? [],
109
+ validate: setup.validate,
110
+ };
111
+ };
112
+
113
+ /**
114
+ * Resolve every installed plugin, keyed by slug. Two plugins on one slug throw,
115
+ * naming both, since handlers could only reach one of them.
116
+ */
117
+ export const resolvePlugins = (declarations: readonly PluginDeclaration[] | undefined, api: PluginApi): Record<string, ResolvedPlugin> => {
118
+ const resolved: Record<string, ResolvedPlugin> = {};
119
+ for (const declaration of declarations ?? []) {
120
+ const existing = resolved[declaration.slug];
121
+ if (existing !== undefined) {
122
+ throw new Error(
123
+ `[kizuna] Two plugins are installed under the slug '${declaration.slug}': '${existing.definedSlug}' and '${declaration.definition.slug}'. Pass one of them a \`slug\` of its own.`
124
+ );
53
125
  }
54
- resolved[pluginKey] = served;
126
+ resolved[declaration.slug] = resolvePlugin(declaration, api);
55
127
  }
56
128
  return resolved;
57
129
  };
130
+
131
+ /**
132
+ * A stand-in for the api that plugins receive in `setup`, before it exists.
133
+ * Reading it inside a handler works once `bind` has run; reading it during
134
+ * `setup` throws, since the api is still being assembled.
135
+ */
136
+ export const createApiReference = (): { api: PluginApi; bind: (target: object) => void } => {
137
+ let current: object | undefined;
138
+ const assembled = (): object => {
139
+ if (current === undefined) {
140
+ throw new Error('[kizuna] A plugin read the api during `setup`. Read it inside a handler, once the config has assembled.');
141
+ }
142
+ return current;
143
+ };
144
+ const api = new Proxy(
145
+ {},
146
+ {
147
+ get: (_target, key) => Reflect.get(assembled(), key),
148
+ has: (_target, key) => Reflect.has(assembled(), key),
149
+ ownKeys: () => Reflect.ownKeys(assembled()),
150
+ getOwnPropertyDescriptor: (_target, key) => {
151
+ const descriptor = Reflect.getOwnPropertyDescriptor(assembled(), key);
152
+ return descriptor === undefined
153
+ ? undefined
154
+ : {
155
+ ...descriptor,
156
+ configurable: true,
157
+ };
158
+ },
159
+ }
160
+ ) as PluginApi;
161
+ return {
162
+ api,
163
+ bind: (target) => {
164
+ current = target;
165
+ },
166
+ };
167
+ };
package/src/plugin.ts CHANGED
@@ -1,8 +1,14 @@
1
+ import { z } from 'zod';
2
+ import { createRoute, type RouteWithHandler } from './route.js';
1
3
  import type { HandlerArgs, HandlerReturn } from './handler-pipeline.js';
2
4
  import type { RawResponse } from './raw-response.js';
3
- import type { RouteDefinition, Routes } from './types.js';
5
+ import type { GeneratedFile } from './config.js';
6
+ import type { AuthoredRouteDefinition, RouteHiddenToolCheck, Routes, RouteDefinition } from './types.js';
4
7
 
5
- export type { RoutePath } from './types.js';
8
+ import type { RoutePath } from './types.js';
9
+
10
+ export type { RoutePath };
11
+ export type { ApiContext } from './configured.js';
6
12
 
7
13
  // Registry-global: adapters read these off the api, and a dual ESM/CJS install
8
14
  // would otherwise hold two different symbols.
@@ -10,115 +16,290 @@ export const PLUGIN_ROUTES_META_KEY: unique symbol = Symbol.for('kizuna.plugin-r
10
16
  export const PLUGIN_SERVERS_META_KEY: unique symbol = Symbol.for('kizuna.plugin-servers') as symbol as typeof PLUGIN_SERVERS_META_KEY;
11
17
 
12
18
  /**
13
- * The routes a plugin serves. `api.mount` serves them through the same pipeline
14
- * as the api's own, but they never join `api.routes`, so the client
15
- * and the generators do not see them.
19
+ * The routes a plugin serves, keyed by name. Each carries its handler, declared
20
+ * with {@link route}.
16
21
  */
17
22
  export type PluginRoutes = Record<string, RouteDefinition>;
18
23
 
19
24
  /**
20
- * What a plugin is: the routes it declares, the props it was configured with,
21
- * and the `serve` that answers them.
25
+ * What a plugin's `setup` returns. Every key is optional, and everything in it
26
+ * shares whatever `setup` created.
22
27
  */
23
- export interface PluginDeclaration<
24
- R extends PluginRoutes = PluginRoutes,
25
- Props = unknown,
26
- Exports = unknown,
27
- Slug extends string = string,
28
- HandlerContext = unknown,
29
- > {
28
+ export interface PluginSetup {
30
29
  /**
31
- * What handlers reach this plugin under, and the key it is installed at.
30
+ * Functions every route and job handler reaches at `plugins.<slug>`.
32
31
  */
32
+ exports?: unknown;
33
33
  /**
34
- * What handlers reach this plugin under, and the key it is installed at.
35
- * Each plugin defaults it; an app installing two of the same plugin gives
36
- * the second one its own.
34
+ * Routes an outside system calls, like a webhook or a status check.
37
35
  */
38
- slug: Slug;
39
- routes: R;
36
+ routes?: PluginRoutes;
40
37
  /**
41
- * Passed to `serve`, so the app never restates it.
38
+ * Files `kizuna generate` writes, built with `defineGenerator`.
42
39
  */
43
- props: Props;
40
+ generators?: readonly GeneratedFile[];
44
41
  /**
45
- * What answers this plugin's routes, and what it hands handlers under
46
- * `plugins.<slug>`.
42
+ * Runs once the config has assembled, with the api available. Throw to stop
43
+ * the app starting, for a check that needs the app's routes or identities.
47
44
  */
48
- serve: (props: Props, api: unknown) => PluginServe<R, Exports, HandlerContext>;
45
+ validate?: () => void;
49
46
  }
50
47
 
51
48
  /**
52
- * What a plugin's `serve` returns: one handler per declared route, and whatever
53
- * it hands handlers under `plugins.<slug>`.
49
+ * The assembled api, as a plugin's handlers read it. It exists once the config
50
+ * has assembled, so read it inside a handler, never in `setup` itself.
51
+ */
52
+ export type PluginApi = Record<string | symbol, unknown> & {
53
+ readonly routes: Routes;
54
+ };
55
+
56
+ /**
57
+ * What `setup` receives.
54
58
  */
55
- export interface PluginServe<R extends PluginRoutes, Exports, HandlerContext> {
56
- router: PluginRouter<R, HandlerContext>;
57
- exports?: Exports;
59
+ export interface PluginSetupContext<Options> {
60
+ /**
61
+ * The options the app passed, validated against the plugin's `options`
62
+ * schema.
63
+ */
64
+ options: Options;
65
+ /**
66
+ * The assembled api, for handlers that read the app's routes or identities.
67
+ */
68
+ api: PluginApi;
58
69
  }
59
70
 
71
+ type OptionsOutput<Schema> = Schema extends z.ZodType ? z.output<Schema> : undefined;
72
+ type OptionsInput<Schema> = Schema extends z.ZodType ? z.input<Schema> : {};
73
+
60
74
  /**
61
- * What {@link createPlugin} takes.
75
+ * What {@link definePlugin} takes.
62
76
  */
63
- export interface PluginDefinition<R extends PluginRoutes, Props, Exports, Slug extends string, HandlerContext> {
77
+ export interface PluginDefinition<
78
+ Slug extends string,
79
+ Schema extends z.ZodType | undefined,
80
+ Setup extends PluginSetup,
81
+ BasePath extends RoutePath | undefined = undefined,
82
+ > {
83
+ /**
84
+ * Handlers reach the plugin at `plugins.<slug>`.
85
+ */
64
86
  slug: Slug;
65
- routes: R;
66
87
  /**
67
- * Passed to `serve`, so the app never restates it.
88
+ * Where the plugin's routes are served. Each route's `path` is relative to
89
+ * it, and a route at `/` serves the base path itself. The app can pass
90
+ * another one when it clashes with its own routes.
91
+ *
92
+ * @example
93
+ * basePath: '/webhooks',
68
94
  */
69
- props?: Props;
70
- serve: (props: NoInfer<Props>, api: unknown) => PluginServe<NoInfer<R>, Exports, HandlerContext>;
95
+ basePath?: BasePath;
96
+ /**
97
+ * A Zod schema for what the app passes in. It's validated once, when the
98
+ * config assembles, and a failure names the plugin and the field.
99
+ */
100
+ options?: Schema;
101
+ /**
102
+ * Builds the plugin from its validated options, once, when the config
103
+ * assembles. It runs during `kizuna generate` too, so it creates clients and
104
+ * leaves connections to the handlers.
105
+ */
106
+ setup: (context: PluginSetupContext<OptionsOutput<Schema>>) => Setup;
71
107
  }
72
108
 
73
109
  /**
74
- * Declare a plugin: the routes it serves, the props an app configures it with,
75
- * and the `serve` that answers those routes. Whatever `serve` returns under
76
- * `exports` reaches every handler as `plugins.<slug>`.
110
+ * One installed plugin: the slug it's installed under, the plugin it is, and the
111
+ * options the app passed, still unvalidated.
112
+ */
113
+ export interface PluginDeclaration<Slug extends string = string, Setup extends PluginSetup = PluginSetup> {
114
+ readonly slug: Slug;
115
+ /**
116
+ * The base path the app passed, when it moved the plugin's routes.
117
+ */
118
+ readonly basePath?: string;
119
+ readonly definition: PluginDefinition<string, z.ZodType | undefined, PluginSetup, RoutePath | undefined>;
120
+ readonly input: unknown;
121
+ /**
122
+ * Carries what `setup` returns, for the types. Never set at runtime.
123
+ */
124
+ readonly setupType?: Setup;
125
+ }
126
+
127
+ /**
128
+ * What {@link definePlugin} returns: the function an app calls in `plugins`.
77
129
  *
78
- * Give the factory a `Slug` parameter and {@link WithSlug} so an app can rename
79
- * what it installs, or install two of them.
130
+ * Two overloads. Passing `slug` installs the plugin under it; leaving it out
131
+ * installs it under the plugin's own. The one without `slug` comes last, so
132
+ * `ReturnType<typeof emailPlugin>`, which `kizuna generate` writes, keeps the
133
+ * plugin's own slug rather than widening it to `string`.
134
+ */
135
+ export type PluginFactory<
136
+ DefaultSlug extends string,
137
+ Schema extends z.ZodType | undefined,
138
+ Setup extends PluginSetup,
139
+ BasePath extends RoutePath | undefined = undefined,
140
+ > =
141
+ {} extends OptionsInput<Schema>
142
+ ? {
143
+ <const Slug extends string>(
144
+ options: OptionsInput<Schema> & InstallOptions<BasePath> & SlugOption<Slug>
145
+ ): PluginDeclaration<Slug, Setup>;
146
+ (options?: OptionsInput<Schema> & InstallOptions<BasePath>): PluginDeclaration<DefaultSlug, Setup>;
147
+ }
148
+ : {
149
+ <const Slug extends string>(
150
+ options: OptionsInput<Schema> & InstallOptions<BasePath> & SlugOption<Slug>
151
+ ): PluginDeclaration<Slug, Setup>;
152
+ (options: OptionsInput<Schema> & InstallOptions<BasePath>): PluginDeclaration<DefaultSlug, Setup>;
153
+ };
154
+
155
+ export interface SlugOption<Slug extends string> {
156
+ /**
157
+ * Install the plugin under another slug, when two plugins want the same one.
158
+ */
159
+ slug: Slug;
160
+ }
161
+
162
+ /**
163
+ * `basePath` at install, offered only by a plugin that declares one.
164
+ */
165
+ export type InstallOptions<BasePath> = BasePath extends RoutePath
166
+ ? {
167
+ /**
168
+ * Serve the plugin's routes somewhere else, when they clash with the
169
+ * app's own.
170
+ */
171
+ basePath?: RoutePath;
172
+ }
173
+ : {
174
+ basePath?: never;
175
+ };
176
+
177
+ /**
178
+ * Declare a plugin: its slug, the options an app passes it, and the `setup` that
179
+ * builds what it brings. Returns the function an app installs it with.
80
180
  *
81
181
  * @example
82
- * ```ts
83
- * const declare = (slug: string, props: AuditProps) =>
84
- * createPlugin({
85
- * slug,
86
- * routes: {
87
- * recent: {
88
- * method: 'GET',
89
- * path: props.path ?? '/audit/recent',
90
- * responses: {
91
- * 200: z.array(EntrySchema),
92
- * },
93
- * },
94
- * },
95
- * props,
96
- * serve: ({ store }) => ({
97
- * router: {
98
- * recent: async () => ({ status: 200, body: await store.recent() }),
99
- * },
182
+ * export const emailPlugin = definePlugin({
183
+ * slug: 'email',
184
+ * options: z.object({
185
+ * apiKey: z.string(),
186
+ * from: z.string(),
187
+ * }),
188
+ * setup: ({ options }) => {
189
+ * const resend = new Resend(options.apiKey);
190
+ *
191
+ * return {
100
192
  * exports: {
101
- * record: (routeKey: string) => store.write(routeKey),
193
+ * send: (email: Email) =>
194
+ * resend.emails.send({
195
+ * from: options.from,
196
+ * ...email,
197
+ * }),
102
198
  * },
103
- * }),
104
- * });
199
+ * };
200
+ * },
201
+ * });
202
+ */
203
+ export const definePlugin = <
204
+ Slug extends string,
205
+ Setup extends PluginSetup,
206
+ Schema extends z.ZodType | undefined = undefined,
207
+ BasePath extends RoutePath | undefined = undefined,
208
+ >(
209
+ definition: PluginDefinition<Slug, Schema, Setup, BasePath>
210
+ ): PluginFactory<Slug, Schema, Setup, BasePath> =>
211
+ ((input?: Record<string, unknown>) => {
212
+ const { slug, basePath, ...options } = input ?? {};
213
+ return {
214
+ slug: typeof slug === 'string' ? slug : definition.slug,
215
+ ...(typeof basePath === 'string'
216
+ ? {
217
+ basePath,
218
+ }
219
+ : {}),
220
+ definition: definition as unknown as PluginDefinition<string, z.ZodType | undefined, PluginSetup, RoutePath | undefined>,
221
+ input: options,
222
+ };
223
+ }) as never;
224
+
225
+ /**
226
+ * Declare one of a plugin's routes and the handler that answers it, the way
227
+ * `k.route` does for an app's own.
105
228
  *
106
- * export function auditPlugin<const Slug extends string = 'audit'>(
107
- * props: AuditProps<Slug>
108
- * ): WithSlug<ReturnType<typeof declare>, Slug> {
109
- * return declare(props.slug ?? 'audit', props) as never;
110
- * }
111
- * ```
112
- */
113
- export const createPlugin = <Props, const R extends PluginRoutes, const Slug extends string, Exports = undefined, HandlerContext = unknown>(
114
- definition: PluginDefinition<R, Props, Exports, Slug, HandlerContext>
115
- ): PluginDeclaration<R, Props, Exports, Slug, HandlerContext> => ({
116
- slug: definition.slug,
117
- routes: definition.routes,
118
- props: definition.props as Props,
119
- serve: definition.serve,
229
+ * @example
230
+ * check: route({
231
+ * method: 'GET',
232
+ * path: '/status',
233
+ * auth: false,
234
+ * responses: {
235
+ * 200: StatusSchema,
236
+ * },
237
+ * }).handler(() => ({
238
+ * status: 200,
239
+ * body: {
240
+ * status: 'ok',
241
+ * },
242
+ * })),
243
+ */
244
+ export const route = createRoute as unknown as <const Definition extends AuthoredRouteDefinition>(
245
+ definition: Definition & RouteHiddenToolCheck<Definition>
246
+ ) => PluginRouteBuilder<Definition>;
247
+
248
+ /**
249
+ * What {@link route} returns: the route, and the `handler` that answers it. A
250
+ * plugin's handler may also answer with `rawResponse` when its wire format is
251
+ * not JSON.
252
+ */
253
+ export type PluginRouteBuilder<Definition extends AuthoredRouteDefinition> = Definition & {
254
+ handler(
255
+ fn: (args: HandlerArgs<Definition>) => Promise<HandlerReturn<Definition> | RawResponse> | HandlerReturn<Definition> | RawResponse
256
+ ): RouteWithHandler<Definition>;
257
+ };
258
+
259
+ /**
260
+ * Accepts a route path, for a plugin that takes one of its routes' paths as an
261
+ * option.
262
+ */
263
+ export const RoutePathSchema = z.custom<RoutePath>((value) => typeof value === 'string' && value.startsWith('/'), {
264
+ error: 'must start with /',
120
265
  });
121
266
 
267
+ /**
268
+ * Accepts exactly what a route's `auth` does, for a plugin that takes one of its
269
+ * routes' `auth` as an option. `defineConfig` checks the value against the app's
270
+ * identities.
271
+ */
272
+ export const RouteAuthSchema = z.union([
273
+ z.literal(false),
274
+ z.string(),
275
+ z.array(z.string()),
276
+ z.object({
277
+ identity: z.union([z.string(), z.array(z.string())]),
278
+ roles: z.union([z.string(), z.array(z.string())]).optional(),
279
+ requires: z.record(z.string(), z.array(z.string())).optional(),
280
+ }),
281
+ ]);
282
+
283
+ /**
284
+ * A plugin once the config has assembled: its options validated and `setup`
285
+ * run.
286
+ */
287
+ export interface ResolvedPlugin {
288
+ /**
289
+ * The slug it's installed under.
290
+ */
291
+ slug: string;
292
+ /**
293
+ * The slug the plugin declared, whatever the app installed it under.
294
+ */
295
+ definedSlug: string;
296
+ options: unknown;
297
+ routes: PluginRoutes;
298
+ exports: unknown;
299
+ generators: readonly GeneratedFile[];
300
+ validate: (() => void) | undefined;
301
+ }
302
+
122
303
  /**
123
304
  * Plugins keyed by their slug, which is what `plugins.*` in handler args
124
305
  * resolves against.
@@ -126,34 +307,16 @@ export const createPlugin = <Props, const R extends PluginRoutes, const Slug ext
126
307
  export type ApiPlugins = Record<string, AnyPlugin>;
127
308
 
128
309
  /**
129
- * Any plugin, whatever it declares. `serve` reads its own props, so a concrete
130
- * plugin is not assignable to a widened one; this stands in wherever a plugin
131
- * is a constraint rather than a value.
310
+ * Any plugin, whatever it declares.
132
311
  */
133
- export type AnyPlugin = PluginDeclaration<any, any, any, string, any>;
312
+ export type AnyPlugin = PluginDeclaration<string, any>;
134
313
 
135
314
  /**
136
- * The plugins a config installs, as an array. Each carries its own slug, which
137
- * is what handlers reach it under.
315
+ * The plugins a config installs, as a list. Each carries its own slug, which is
316
+ * what handlers reach it under.
138
317
  */
139
318
  export type PluginList = readonly AnyPlugin[];
140
319
 
141
- /**
142
- * One plugin declaration under a different slug, for a factory that lets an app
143
- * rename what it installs.
144
- *
145
- * @example
146
- * export function auditPlugin<const Slug extends string = 'audit'>(
147
- * props?: AuditProps<Slug>
148
- * ): WithSlug<ReturnType<typeof declare>, Slug> {
149
- * return declare(props?.slug ?? 'audit', props ?? {}) as never;
150
- * }
151
- */
152
- export type WithSlug<Declaration, Slug extends string> =
153
- Declaration extends PluginDeclaration<infer R, infer Props, infer Exports, string, infer HandlerContext>
154
- ? PluginDeclaration<R, Props, Exports, Slug, HandlerContext>
155
- : never;
156
-
157
320
  /**
158
321
  * A plugin list as a record keyed by each plugin's own slug.
159
322
  */
@@ -161,13 +324,11 @@ export type PluginsBySlug<Plugins extends PluginList> = {
161
324
  [Plugin in Plugins[number] as Plugin['slug']]: Plugin;
162
325
  };
163
326
 
164
- export type PluginRoutesOf<Declaration> = Declaration extends PluginDeclaration<infer R, infer _P, infer _E, string, infer _H> ? R : never;
327
+ type SetupOf<Declaration> = Declaration extends PluginDeclaration<string, infer Setup> ? Setup : never;
165
328
 
166
- export type PluginPropsOf<Declaration> =
167
- Declaration extends PluginDeclaration<infer _R, infer Props, infer _E, string, infer _H> ? Props : never;
329
+ export type PluginRoutesOf<Declaration> = SetupOf<Declaration> extends { routes: infer R extends PluginRoutes } ? R : Record<string, never>;
168
330
 
169
- export type PluginExportsOf<Declaration> =
170
- Declaration extends PluginDeclaration<infer _R, infer _P, infer Exports, string, infer _H> ? Exports : never;
331
+ export type PluginExportsOf<Declaration> = SetupOf<Declaration> extends { exports: infer Exports } ? Exports : undefined;
171
332
 
172
333
  export type PluginExportValues<Plugins extends ApiPlugins> = {
173
334
  [Key in keyof Plugins]: PluginExportsOf<Plugins[Key]>;
@@ -186,32 +347,13 @@ export type PluginArgs<Plugins extends ApiPlugins> = string extends keyof Plugin
186
347
  };
187
348
 
188
349
  /**
189
- * Every plugin's routes as one tree, keyed by install name, for the adapter to
190
- * walk as it walks the api's own.
350
+ * Every plugin's routes as one tree, keyed by slug, for the adapter to walk as
351
+ * it walks the api's own.
191
352
  */
192
- export const pluginRouteTree = (plugins: ApiPlugins | undefined): Routes => {
353
+ export const pluginRouteTree = (plugins: Record<string, { routes: PluginRoutes }> | undefined): Routes => {
193
354
  const tree: Record<string, unknown> = {};
194
- for (const [pluginKey, plugin] of Object.entries(plugins ?? {})) {
195
- tree[pluginKey] = plugin.routes;
355
+ for (const [slug, plugin] of Object.entries(plugins ?? {})) {
356
+ tree[slug] = plugin.routes;
196
357
  }
197
358
  return tree as Routes;
198
359
  };
199
-
200
- /**
201
- * A plugin's handlers, typed against its routes. A plugin may also answer with
202
- * {@link rawResponse} when its wire format is not JSON.
203
- */
204
- export type PluginRouter<R extends PluginRoutes, HandlerContext> = {
205
- [Key in keyof R]: (
206
- args: HandlerArgs<R[Key]> & HandlerContext
207
- ) => Promise<HandlerReturn<R[Key]> | RawResponse> | HandlerReturn<R[Key]> | RawResponse;
208
- };
209
-
210
- /**
211
- * Every plugin in a list, keyed by its own slug.
212
- */
213
- export const pluginsBySlug = (plugins: PluginList | undefined): ApiPlugins => {
214
- const bySlug: Record<string, unknown> = {};
215
- for (const plugin of plugins ?? []) bySlug[plugin.slug] = plugin;
216
- return bySlug as ApiPlugins;
217
- };