@clegra/sdk 0.0.0-stage → 0.1.0-next.1

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/CHANGELOG.md +158 -0
  2. package/LICENSE +21 -0
  3. package/NOTICE.md +25 -0
  4. package/README.md +258 -2
  5. package/dist/spec/kinds.json +211 -0
  6. package/dist/spec/schema/clegra.schema.json +1249 -0
  7. package/dist/spec/src/cli.d.ts +2 -0
  8. package/dist/spec/src/cli.js +21 -0
  9. package/dist/spec/src/cli.js.map +1 -0
  10. package/dist/spec/src/conformance.d.ts +34 -0
  11. package/dist/spec/src/conformance.js +704 -0
  12. package/dist/spec/src/conformance.js.map +1 -0
  13. package/dist/spec/src/init/index.d.ts +31 -0
  14. package/dist/spec/src/init/index.js +151 -0
  15. package/dist/spec/src/init/index.js.map +1 -0
  16. package/dist/spec/src/init/next-config.d.ts +19 -0
  17. package/dist/spec/src/init/next-config.js +77 -0
  18. package/dist/spec/src/init/next-config.js.map +1 -0
  19. package/dist/spec/src/init/project.d.ts +44 -0
  20. package/dist/spec/src/init/project.js +141 -0
  21. package/dist/spec/src/init/project.js.map +1 -0
  22. package/dist/spec/src/init/templates.d.ts +20 -0
  23. package/dist/spec/src/init/templates.js +166 -0
  24. package/dist/spec/src/init/templates.js.map +1 -0
  25. package/dist/spec/src/init/ui.d.ts +30 -0
  26. package/dist/spec/src/init/ui.js +82 -0
  27. package/dist/spec/src/init/ui.js.map +1 -0
  28. package/dist/spec/src/kinds.d.ts +89 -0
  29. package/dist/spec/src/kinds.js +319 -0
  30. package/dist/spec/src/kinds.js.map +1 -0
  31. package/dist/spec/src/protocol.d.ts +50 -0
  32. package/dist/spec/src/protocol.js +52 -0
  33. package/dist/spec/src/protocol.js.map +1 -0
  34. package/dist/spec/src/rules.d.ts +132 -0
  35. package/dist/spec/src/rules.js +282 -0
  36. package/dist/spec/src/rules.js.map +1 -0
  37. package/dist/src/auth.d.ts +371 -0
  38. package/dist/src/auth.js +964 -0
  39. package/dist/src/auth.js.map +1 -0
  40. package/dist/src/define.d.ts +249 -0
  41. package/dist/src/define.js +83 -0
  42. package/dist/src/define.js.map +1 -0
  43. package/dist/src/embed.d.ts +98 -0
  44. package/dist/src/embed.js +256 -0
  45. package/dist/src/embed.js.map +1 -0
  46. package/dist/src/index.d.ts +11 -0
  47. package/dist/src/index.js +11 -0
  48. package/dist/src/index.js.map +1 -0
  49. package/dist/src/labels.d.ts +10 -0
  50. package/dist/src/labels.js +22 -0
  51. package/dist/src/labels.js.map +1 -0
  52. package/dist/src/manifest.d.ts +499 -0
  53. package/dist/src/manifest.js +188 -0
  54. package/dist/src/manifest.js.map +1 -0
  55. package/dist/src/meaning.d.ts +64 -0
  56. package/dist/src/meaning.js +116 -0
  57. package/dist/src/meaning.js.map +1 -0
  58. package/dist/src/next/index.d.ts +101 -0
  59. package/dist/src/next/index.js +187 -0
  60. package/dist/src/next/index.js.map +1 -0
  61. package/dist/src/node.d.ts +14 -0
  62. package/dist/src/node.js +64 -0
  63. package/dist/src/node.js.map +1 -0
  64. package/dist/src/server.d.ts +229 -0
  65. package/dist/src/server.js +2256 -0
  66. package/dist/src/server.js.map +1 -0
  67. package/dist/src/store.d.ts +129 -0
  68. package/dist/src/store.js +213 -0
  69. package/dist/src/store.js.map +1 -0
  70. package/dist/src/testing.d.ts +133 -0
  71. package/dist/src/testing.js +81 -0
  72. package/dist/src/testing.js.map +1 -0
  73. package/dist/src/types.d.ts +352 -0
  74. package/dist/src/types.js +2 -0
  75. package/dist/src/types.js.map +1 -0
  76. package/dist/src/view.d.ts +35 -0
  77. package/dist/src/view.js +442 -0
  78. package/dist/src/view.js.map +1 -0
  79. package/docs/quickstart.md +350 -0
  80. package/docs/spec.md +997 -0
  81. package/package.json +89 -4
@@ -0,0 +1,352 @@
1
+ import type { z } from "zod";
2
+ import type { EntityKind, PropertyDef } from "../spec/src/kinds.js";
3
+ import type { Caller, Person } from "./auth.js";
4
+ import type { Label } from "./labels.js";
5
+ import type { FieldInfo } from "./meaning.js";
6
+ /** What every handler gets: who is calling, for which installation, in which language. */
7
+ export type Context = {
8
+ readonly app: string;
9
+ /** The tenant (spec §7): the installation bound to its issuer (`<installation>@<issuer>`). Scope every read and write by it. */
10
+ readonly installation: string;
11
+ readonly person: Person | null;
12
+ readonly permissions: ReadonlySet<string>;
13
+ can(permission: string): boolean;
14
+ readonly locale: string;
15
+ readonly host: Caller["host"];
16
+ /** The installation's settings (spec §2), as its workspace host sent them, defaults filled in. A plain client's are the defaults. */
17
+ readonly settings: Readonly<Record<string, unknown>>;
18
+ /** The call id (`_meta.clegra.call`), when the host sent one. */
19
+ readonly call: string | null;
20
+ /** The schedule this call is a run of (`_meta.clegra.schedule`; `clegra_later` for a later run), else null. Such a call has no person. */
21
+ readonly schedule: string | null;
22
+ /** In a later run: the run (its id, when it was due, its deadline and when the person confirmed it, epoch seconds but `at`). Else null. */
23
+ readonly later: LaterInfo | null;
24
+ /** Cancels a pending later run of this tenant: false when there is none with this id, or it already ran or started. */
25
+ cancelLater(id: string): Promise<boolean>;
26
+ /** A label in the caller's language. */
27
+ t(label: Label | undefined): string;
28
+ /**
29
+ * A notification for the workspace host to deliver to people of the installation (spec §7). With declared
30
+ * `notifications`, each names one of their types; without, none does. A call without a person says `to`.
31
+ * Throws (a programming error) otherwise.
32
+ */
33
+ notify(notification: Notification): void;
34
+ /** The URI of a record of this app. */
35
+ uri(entity: string | EntityHandle, id: string): string;
36
+ };
37
+ /**
38
+ * `to`: person ids, or everyone of the installation who holds a declared permission (default: the caller's person).
39
+ * `type`: one of the app's declared notification types (people mute a type per app).
40
+ */
41
+ export type Notification = {
42
+ type?: string;
43
+ title: Label;
44
+ body?: Label;
45
+ uri?: string;
46
+ to?: string[] | {
47
+ permission: string;
48
+ };
49
+ };
50
+ /** A later run, as its handler sees it (`ctx.later`): `at` as the person gave it, `until` and `confirmedAt` in epoch seconds. */
51
+ export type LaterInfo = {
52
+ id: string;
53
+ at: string;
54
+ until: number;
55
+ confirmedAt: number;
56
+ };
57
+ /** Who sees an entity, action or fragment: `"app"` keeps it from every model (only views and the host's own UI use it). */
58
+ export type Visibility = "app";
59
+ /** What a host offers a global action on: an email, or a record of a kind in any app of the workspace. */
60
+ export type TargetName = "mail.message" | `record:${string}`;
61
+ /** A target of an action (`targets`): what it needs of the object, and its input as a template (`{from.address}`, `{uri}`, `{title}`). */
62
+ export type Target<In = Record<string, unknown>> = {
63
+ target: TargetName;
64
+ needs: string[];
65
+ input?: {
66
+ [K in keyof In]?: unknown;
67
+ };
68
+ label?: Label;
69
+ };
70
+ /** «Approve now, act later»: the date-time input `at` says when the confirmed call runs, within `window` minutes (default 60). */
71
+ export type LaterConfig<In = Record<string, unknown>> = {
72
+ at: keyof In & string;
73
+ window?: number;
74
+ };
75
+ /** What an installation went to: the host tells the app (`lifecycle.installation`). */
76
+ export type InstallationState = "enabled" | "disabled" | "uninstalled";
77
+ /** The tenant's data as one file (`lifecycle.export`): `name` defaults to `<app>-export`. */
78
+ export type ExportFile = {
79
+ name?: string;
80
+ contentType: string;
81
+ body: string | Uint8Array;
82
+ };
83
+ /**
84
+ * The app's lifecycle, called only by the workspace host as the installation: told of each change of its
85
+ * installation, the tenant's data exported, everything it keeps for the tenant deleted (also after `uninstalled`).
86
+ */
87
+ export type LifecycleConfig = {
88
+ installation?: (state: InstallationState, ctx: Context) => Promise<void> | void;
89
+ export?: (ctx: Context) => Promise<ExportFile | null> | ExportFile | null;
90
+ delete?: (ctx: Context) => Promise<{
91
+ counts?: Record<string, number>;
92
+ } | void> | {
93
+ counts?: Record<string, number>;
94
+ } | void;
95
+ };
96
+ /** A schedule (`schedules`): a global action the workspace host runs as the installation every `every` minutes, within `maxSeconds` (default 60). */
97
+ export type ScheduleConfig = {
98
+ action: ActionHandle;
99
+ every: number;
100
+ maxSeconds?: number;
101
+ };
102
+ /** A notification type (`notifications`): people mute it per app; `default: false` keeps it off until they turn it on. */
103
+ /** Who publishes an app (manifest `publisher`, spec §2): a claim that grants nothing; a store may verify it by the url's domain. */
104
+ export type Publisher = {
105
+ name: string;
106
+ url: string;
107
+ };
108
+ export type NotificationTypeConfig = {
109
+ label: Label;
110
+ description?: Label;
111
+ default?: boolean;
112
+ permission?: string;
113
+ };
114
+ /** A navigation section (`nav`): its label and its pages, in order. */
115
+ export type NavSection = {
116
+ section?: Label;
117
+ pages: string[];
118
+ };
119
+ export type Value = string | number | boolean;
120
+ export type Filter = Value | {
121
+ in: Value[];
122
+ } | {
123
+ gte?: Value;
124
+ lte?: Value;
125
+ };
126
+ /** What `list` receives (spec §4), already checked against the fields' meaning and the caller's field permissions. */
127
+ export type Query = {
128
+ filters: Record<string, Filter>;
129
+ /** Text to search for, only in `textFields`. */
130
+ text?: string;
131
+ /** With `text`: the search fields this caller may see. Search in these and no other (a hidden field must not answer). */
132
+ textFields?: string[];
133
+ sort?: {
134
+ field: string;
135
+ dir: "asc" | "desc";
136
+ };
137
+ cursor?: string;
138
+ limit: number;
139
+ };
140
+ export type ListResult<Row> = {
141
+ rows: Row[];
142
+ next?: string;
143
+ total?: number;
144
+ };
145
+ export type EntityConfig<S extends z.ZodObject> = {
146
+ label: Label;
147
+ plural?: Label;
148
+ description?: Label;
149
+ /** A lucide icon name. */
150
+ icon?: string;
151
+ /** What the entity is (spec §3.1): a kind, or `{ by, map }` for one kind per record. */
152
+ kind?: EntityKind;
153
+ schema: S;
154
+ /** Who may see records of this entity at all. */
155
+ permission?: string;
156
+ get: (id: string, ctx: Context) => Promise<z.infer<S> | null> | z.infer<S> | null;
157
+ list: (query: Query, ctx: Context) => Promise<ListResult<z.infer<S>>> | ListResult<z.infer<S>>;
158
+ /** Plain MCP clients: listed (default true) and the tool names (default `<entity>_list`, `<entity>_get`). */
159
+ expose?: {
160
+ plain?: boolean;
161
+ list?: string;
162
+ get?: string;
163
+ };
164
+ /** Your own ui:// view for a record, instead of the generated one. */
165
+ view?: ViewSource;
166
+ visibility?: Visibility;
167
+ };
168
+ /** An entity, as the SDK knows it once defined. */
169
+ export type EntityHandle<S extends z.ZodObject = z.ZodObject> = {
170
+ readonly kind: "entity";
171
+ readonly name: string;
172
+ readonly schema: S;
173
+ readonly fields: readonly FieldInfo[];
174
+ uri(id: string): string;
175
+ };
176
+ export type Confirm = "always" | "optional" | "never";
177
+ export type ActionResult = {
178
+ message?: string;
179
+ record?: string;
180
+ data?: Record<string, unknown>;
181
+ };
182
+ export type ActionConfig<I extends z.ZodObject, E extends EntityHandle | undefined> = {
183
+ entity?: E;
184
+ title: Label;
185
+ description?: Label;
186
+ icon?: string;
187
+ input?: I;
188
+ /** A read: changes nothing (its confirm is `never`). */
189
+ readOnly?: boolean;
190
+ /** Default `always` for writes. */
191
+ confirm?: Confirm;
192
+ permission?: string;
193
+ /** Plain MCP clients: reads are listed by default, writes only with `plain: true`; `tool` renames the tool. */
194
+ expose?: {
195
+ plain?: boolean;
196
+ tool?: string;
197
+ };
198
+ visibility?: Visibility;
199
+ targets?: Target<z.infer<I>>[];
200
+ later?: LaterConfig<z.infer<I>>;
201
+ };
202
+ export type ActionHandler<I extends z.ZodObject, E extends EntityHandle | undefined> = (input: z.infer<I>, ctx: Context, record: E extends EntityHandle<infer S> ? z.infer<S> : undefined) => Promise<ActionResult | void> | ActionResult | void;
203
+ export type ActionHandle = {
204
+ readonly kind: "action";
205
+ readonly name: string;
206
+ readonly tool: string;
207
+ };
208
+ export type Exposure = {
209
+ plain?: boolean;
210
+ tool?: string;
211
+ };
212
+ export type FragmentInstance = {
213
+ type: string;
214
+ params: Record<string, unknown>;
215
+ size?: "small" | "medium" | "large";
216
+ };
217
+ type PageBase<P extends z.ZodObject> = {
218
+ title: Label;
219
+ icon?: string;
220
+ permission?: string;
221
+ description?: Label;
222
+ params?: P;
223
+ expose?: Exposure;
224
+ /** Global actions offered on the page; the first is its primary. Page params prefill inputs of the same name. */
225
+ actions?: ActionHandle[];
226
+ /** A `stat` fragment type without required params: its value is the page's count in the navigation. */
227
+ badge?: string;
228
+ };
229
+ export type PageConfig<P extends z.ZodObject = z.ZodObject> = (PageBase<P> & {
230
+ kind: "list";
231
+ entity: EntityHandle;
232
+ columns: string[];
233
+ /** From the page's params to the list query (default: params are the filter fields and `text`). */
234
+ query?: (params: z.infer<P>) => Partial<Pick<Query, "filters" | "text" | "sort">>;
235
+ /** Your own ui:// view instead of the generated one (hosts may still draw the list natively). */
236
+ view?: ViewSource;
237
+ }) | (Omit<PageBase<P>, "params" | "title" | "actions" | "badge"> & {
238
+ kind: "record";
239
+ entity: EntityHandle;
240
+ title?: Label;
241
+ sections?: {
242
+ title: Label;
243
+ fields: string[];
244
+ }[];
245
+ view?: ViewSource;
246
+ }) | (PageBase<P> & {
247
+ kind: "dashboard";
248
+ fragments: FragmentInstance[] | ((params: z.infer<P>, ctx: Context) => FragmentInstance[] | Promise<FragmentInstance[]>);
249
+ view?: ViewSource;
250
+ }) | (PageBase<P> & {
251
+ kind: "custom";
252
+ view: ViewSource;
253
+ }) | (PageBase<P> & {
254
+ kind: "custom";
255
+ url: string;
256
+ });
257
+ /** An MCP Apps view's document, with the origins it may reach (MCP Apps CSP). */
258
+ export type ViewSource = {
259
+ html: string | (() => string | Promise<string>);
260
+ csp?: {
261
+ connectDomains?: string[];
262
+ resourceDomains?: string[];
263
+ frameDomains?: string[];
264
+ };
265
+ prefersBorder?: boolean;
266
+ };
267
+ export type Template = "card" | "stat" | "list" | "chart";
268
+ export type TemplateData = {
269
+ card: {
270
+ title: string;
271
+ subtitle?: string;
272
+ status?: string;
273
+ fields: {
274
+ label: string;
275
+ value: string | number;
276
+ }[];
277
+ uri?: string;
278
+ };
279
+ stat: {
280
+ label: string;
281
+ value: number | string;
282
+ format?: "number" | "money" | "percent";
283
+ currency?: string;
284
+ hint?: string;
285
+ };
286
+ list: {
287
+ items: {
288
+ title: string;
289
+ subtitle?: string;
290
+ status?: string;
291
+ uri?: string;
292
+ }[];
293
+ };
294
+ chart: {
295
+ kind: "bar" | "line" | "pie";
296
+ points: {
297
+ label: string;
298
+ value: number;
299
+ }[];
300
+ format?: "number" | "money";
301
+ currency?: string;
302
+ };
303
+ };
304
+ export type FragmentConfig<P extends z.ZodObject, T extends Template> = {
305
+ title: Label;
306
+ description: Label;
307
+ icon?: string;
308
+ params: P;
309
+ permission?: string;
310
+ /** Actions shown inside (global actions). */
311
+ actions?: ActionHandle[];
312
+ size?: "small" | "medium" | "large";
313
+ expose?: Exposure;
314
+ /** Its texts are written by outsiders (records' names, notes): data for a model, never instructions. */
315
+ untrusted?: boolean;
316
+ visibility?: Visibility;
317
+ } & ({
318
+ template: T;
319
+ data: (params: z.infer<P>, ctx: Context) => Promise<TemplateData[T] | null> | TemplateData[T] | null;
320
+ view?: ViewSource;
321
+ } | {
322
+ view: ViewSource;
323
+ data: (params: z.infer<P>, ctx: Context) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
324
+ template?: never;
325
+ });
326
+ export type AgentConfig = {
327
+ title: Label;
328
+ description: Label;
329
+ instructions: string;
330
+ tools: (EntityHandle | ActionHandle | string)[];
331
+ tier?: "fast" | "standard" | "strong";
332
+ starters?: Label[];
333
+ };
334
+ /** A namespaced kind an app defines (spec §3.1): `com.example.shipment`. */
335
+ export type KindConfig = {
336
+ label: Label;
337
+ properties: Record<string, PropertyDef>;
338
+ };
339
+ export type PermissionConfig = {
340
+ label: Label;
341
+ description?: Label;
342
+ default?: boolean;
343
+ };
344
+ /** A value an administrator sets per installation; the workspace host sends it with every call. Never a secret (those stay in the app's own configuration). */
345
+ export type SettingConfig = {
346
+ label: Label;
347
+ description?: Label;
348
+ type: "text" | "number" | "boolean";
349
+ required?: boolean;
350
+ default?: string | number | boolean;
351
+ };
352
+ export {};
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { z } from \"zod\"\n\nimport type { EntityKind, PropertyDef } from \"../spec/src/kinds\"\nimport type { Caller, Person } from \"./auth\"\nimport type { Label } from \"./labels\"\nimport type { FieldInfo } from \"./meaning\"\n\n/** What every handler gets: who is calling, for which installation, in which language. */\nexport type Context = {\n readonly app: string\n /** The tenant (spec §7): the installation bound to its issuer (`<installation>@<issuer>`). Scope every read and write by it. */\n readonly installation: string\n readonly person: Person | null\n readonly permissions: ReadonlySet<string>\n can(permission: string): boolean\n readonly locale: string\n readonly host: Caller[\"host\"]\n /** The installation's settings (spec §2), as its workspace host sent them, defaults filled in. A plain client's are the defaults. */\n readonly settings: Readonly<Record<string, unknown>>\n /** The call id (`_meta.clegra.call`), when the host sent one. */\n readonly call: string | null\n /** The schedule this call is a run of (`_meta.clegra.schedule`; `clegra_later` for a later run), else null. Such a call has no person. */\n readonly schedule: string | null\n /** In a later run: the run (its id, when it was due, its deadline and when the person confirmed it, epoch seconds but `at`). Else null. */\n readonly later: LaterInfo | null\n /** Cancels a pending later run of this tenant: false when there is none with this id, or it already ran or started. */\n cancelLater(id: string): Promise<boolean>\n /** A label in the caller's language. */\n t(label: Label | undefined): string\n /**\n * A notification for the workspace host to deliver to people of the installation (spec §7). With declared\n * `notifications`, each names one of their types; without, none does. A call without a person says `to`.\n * Throws (a programming error) otherwise.\n */\n notify(notification: Notification): void\n /** The URI of a record of this app. */\n uri(entity: string | EntityHandle, id: string): string\n}\n\n/**\n * `to`: person ids, or everyone of the installation who holds a declared permission (default: the caller's person).\n * `type`: one of the app's declared notification types (people mute a type per app).\n */\nexport type Notification = { type?: string; title: Label; body?: Label; uri?: string; to?: string[] | { permission: string } }\n\n/** A later run, as its handler sees it (`ctx.later`): `at` as the person gave it, `until` and `confirmedAt` in epoch seconds. */\nexport type LaterInfo = { id: string; at: string; until: number; confirmedAt: number }\n\n/** Who sees an entity, action or fragment: `\"app\"` keeps it from every model (only views and the host's own UI use it). */\nexport type Visibility = \"app\"\n\n/** What a host offers a global action on: an email, or a record of a kind in any app of the workspace. */\nexport type TargetName = \"mail.message\" | `record:${string}`\n\n/** A target of an action (`targets`): what it needs of the object, and its input as a template (`{from.address}`, `{uri}`, `{title}`). */\nexport type Target<In = Record<string, unknown>> = { target: TargetName; needs: string[]; input?: { [K in keyof In]?: unknown }; label?: Label }\n\n/** «Approve now, act later»: the date-time input `at` says when the confirmed call runs, within `window` minutes (default 60). */\nexport type LaterConfig<In = Record<string, unknown>> = { at: keyof In & string; window?: number }\n\n/** What an installation went to: the host tells the app (`lifecycle.installation`). */\nexport type InstallationState = \"enabled\" | \"disabled\" | \"uninstalled\"\n\n/** The tenant's data as one file (`lifecycle.export`): `name` defaults to `<app>-export`. */\nexport type ExportFile = { name?: string; contentType: string; body: string | Uint8Array }\n\n/**\n * The app's lifecycle, called only by the workspace host as the installation: told of each change of its\n * installation, the tenant's data exported, everything it keeps for the tenant deleted (also after `uninstalled`).\n */\nexport type LifecycleConfig = {\n installation?: (state: InstallationState, ctx: Context) => Promise<void> | void\n export?: (ctx: Context) => Promise<ExportFile | null> | ExportFile | null\n delete?: (ctx: Context) => Promise<{ counts?: Record<string, number> } | void> | { counts?: Record<string, number> } | void\n}\n\n/** A schedule (`schedules`): a global action the workspace host runs as the installation every `every` minutes, within `maxSeconds` (default 60). */\nexport type ScheduleConfig = { action: ActionHandle; every: number; maxSeconds?: number }\n\n/** A notification type (`notifications`): people mute it per app; `default: false` keeps it off until they turn it on. */\n/** Who publishes an app (manifest `publisher`, spec §2): a claim that grants nothing; a store may verify it by the url's domain. */\nexport type Publisher = { name: string; url: string }\nexport type NotificationTypeConfig = { label: Label; description?: Label; default?: boolean; permission?: string }\n\n/** A navigation section (`nav`): its label and its pages, in order. */\nexport type NavSection = { section?: Label; pages: string[] }\n\nexport type Value = string | number | boolean\nexport type Filter = Value | { in: Value[] } | { gte?: Value; lte?: Value }\n\n/** What `list` receives (spec §4), already checked against the fields' meaning and the caller's field permissions. */\nexport type Query = {\n filters: Record<string, Filter>\n /** Text to search for, only in `textFields`. */\n text?: string\n /** With `text`: the search fields this caller may see. Search in these and no other (a hidden field must not answer). */\n textFields?: string[]\n sort?: { field: string; dir: \"asc\" | \"desc\" }\n cursor?: string\n limit: number\n}\n\nexport type ListResult<Row> = { rows: Row[]; next?: string; total?: number }\n\nexport type EntityConfig<S extends z.ZodObject> = {\n label: Label\n plural?: Label\n description?: Label\n /** A lucide icon name. */\n icon?: string\n /** What the entity is (spec §3.1): a kind, or `{ by, map }` for one kind per record. */\n kind?: EntityKind\n schema: S\n /** Who may see records of this entity at all. */\n permission?: string\n get: (id: string, ctx: Context) => Promise<z.infer<S> | null> | z.infer<S> | null\n list: (query: Query, ctx: Context) => Promise<ListResult<z.infer<S>>> | ListResult<z.infer<S>>\n /** Plain MCP clients: listed (default true) and the tool names (default `<entity>_list`, `<entity>_get`). */\n expose?: { plain?: boolean; list?: string; get?: string }\n /** Your own ui:// view for a record, instead of the generated one. */\n view?: ViewSource\n visibility?: Visibility\n}\n\n/** An entity, as the SDK knows it once defined. */\nexport type EntityHandle<S extends z.ZodObject = z.ZodObject> = {\n readonly kind: \"entity\"\n readonly name: string\n readonly schema: S\n readonly fields: readonly FieldInfo[]\n uri(id: string): string\n}\n\nexport type Confirm = \"always\" | \"optional\" | \"never\"\n\nexport type ActionResult = { message?: string; record?: string; data?: Record<string, unknown> }\n\nexport type ActionConfig<I extends z.ZodObject, E extends EntityHandle | undefined> = {\n entity?: E\n title: Label\n description?: Label\n icon?: string\n input?: I\n /** A read: changes nothing (its confirm is `never`). */\n readOnly?: boolean\n /** Default `always` for writes. */\n confirm?: Confirm\n permission?: string\n /** Plain MCP clients: reads are listed by default, writes only with `plain: true`; `tool` renames the tool. */\n expose?: { plain?: boolean; tool?: string }\n visibility?: Visibility\n targets?: Target<z.infer<I>>[]\n later?: LaterConfig<z.infer<I>>\n}\n\nexport type ActionHandler<I extends z.ZodObject, E extends EntityHandle | undefined> = (\n input: z.infer<I>,\n ctx: Context,\n record: E extends EntityHandle<infer S> ? z.infer<S> : undefined,\n) => Promise<ActionResult | void> | ActionResult | void\n\nexport type ActionHandle = { readonly kind: \"action\"; readonly name: string; readonly tool: string }\n\nexport type Exposure = { plain?: boolean; tool?: string }\n\nexport type FragmentInstance = { type: string; params: Record<string, unknown>; size?: \"small\" | \"medium\" | \"large\" }\n\ntype PageBase<P extends z.ZodObject> = {\n title: Label\n icon?: string\n permission?: string\n description?: Label\n params?: P\n expose?: Exposure\n /** Global actions offered on the page; the first is its primary. Page params prefill inputs of the same name. */\n actions?: ActionHandle[]\n /** A `stat` fragment type without required params: its value is the page's count in the navigation. */\n badge?: string\n}\n\nexport type PageConfig<P extends z.ZodObject = z.ZodObject> =\n | (PageBase<P> & {\n kind: \"list\"\n entity: EntityHandle\n columns: string[]\n /** From the page's params to the list query (default: params are the filter fields and `text`). */\n query?: (params: z.infer<P>) => Partial<Pick<Query, \"filters\" | \"text\" | \"sort\">>\n /** Your own ui:// view instead of the generated one (hosts may still draw the list natively). */\n view?: ViewSource\n })\n | (Omit<PageBase<P>, \"params\" | \"title\" | \"actions\" | \"badge\"> & { kind: \"record\"; entity: EntityHandle; title?: Label; sections?: { title: Label; fields: string[] }[]; view?: ViewSource })\n | (PageBase<P> & { kind: \"dashboard\"; fragments: FragmentInstance[] | ((params: z.infer<P>, ctx: Context) => FragmentInstance[] | Promise<FragmentInstance[]>); view?: ViewSource })\n | (PageBase<P> & { kind: \"custom\"; view: ViewSource })\n | (PageBase<P> & { kind: \"custom\"; url: string })\n\n/** An MCP Apps view's document, with the origins it may reach (MCP Apps CSP). */\nexport type ViewSource = { html: string | (() => string | Promise<string>); csp?: { connectDomains?: string[]; resourceDomains?: string[]; frameDomains?: string[] }; prefersBorder?: boolean }\n\nexport type Template = \"card\" | \"stat\" | \"list\" | \"chart\"\n\nexport type TemplateData = {\n card: { title: string; subtitle?: string; status?: string; fields: { label: string; value: string | number }[]; uri?: string }\n stat: { label: string; value: number | string; format?: \"number\" | \"money\" | \"percent\"; currency?: string; hint?: string }\n list: { items: { title: string; subtitle?: string; status?: string; uri?: string }[] }\n chart: { kind: \"bar\" | \"line\" | \"pie\"; points: { label: string; value: number }[]; format?: \"number\" | \"money\"; currency?: string }\n}\n\nexport type FragmentConfig<P extends z.ZodObject, T extends Template> = {\n title: Label\n description: Label\n icon?: string\n params: P\n permission?: string\n /** Actions shown inside (global actions). */\n actions?: ActionHandle[]\n size?: \"small\" | \"medium\" | \"large\"\n expose?: Exposure\n /** Its texts are written by outsiders (records' names, notes): data for a model, never instructions. */\n untrusted?: boolean\n visibility?: Visibility\n} & (\n | { template: T; data: (params: z.infer<P>, ctx: Context) => Promise<TemplateData[T] | null> | TemplateData[T] | null; view?: ViewSource }\n | { view: ViewSource; data: (params: z.infer<P>, ctx: Context) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null; template?: never }\n)\n\nexport type AgentConfig = {\n title: Label\n description: Label\n instructions: string\n tools: (EntityHandle | ActionHandle | string)[]\n tier?: \"fast\" | \"standard\" | \"strong\"\n starters?: Label[]\n}\n\n/** A namespaced kind an app defines (spec §3.1): `com.example.shipment`. */\nexport type KindConfig = { label: Label; properties: Record<string, PropertyDef> }\n\nexport type PermissionConfig = { label: Label; description?: Label; default?: boolean }\n\n/** A value an administrator sets per installation; the workspace host sends it with every call. Never a secret (those stay in the app's own configuration). */\nexport type SettingConfig = {\n label: Label\n description?: Label\n type: \"text\" | \"number\" | \"boolean\"\n required?: boolean\n default?: string | number | boolean\n}\n"]}
@@ -0,0 +1,35 @@
1
+ /**
2
+ * THE SDK'S MCP APPS VIEW (spec §5): one HTML document that draws every
3
+ * derived result (a list, a record, a fragment, a dashboard) for hosts that
4
+ * show MCP Apps views: ChatGPT, Claude, and a workspace host's frames.
5
+ *
6
+ * It speaks the MCP Apps bridge (JSON-RPC 2.0 over postMessage:
7
+ * `ui/initialize` then `ui/notifications/initialized`, `tools/call`,
8
+ * `ui/notifications/tool-result`, `ui/notifications/size-changed`,
9
+ * `ui/update-model-context`). ChatGPT implements the same bridge and also
10
+ * injects `window.openai`: the view draws its first result from
11
+ * `window.openai.toolOutput` when that is there first, but calls tools over the
12
+ * standard bridge; `window.openai.callTool` is used only by a host that did not
13
+ * answer `ui/initialize`. Data arrives as the tool result's `structuredContent`;
14
+ * a page opened with no tool call (`boot`) asks for its own data. No network
15
+ * access: the host relays every call, with its permissions and confirmations.
16
+ * A click always shows something: progress at once, then the record, or what
17
+ * the host or the app said, in a status line at the top of the view.
18
+ */
19
+ export declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
20
+ export declare const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
21
+ /** The view document; `boot` names the tool a page calls for its own data when no tool result opens it. */
22
+ export declare function viewHtml(title: string, boot?: {
23
+ tool: string;
24
+ args?: Record<string, unknown>;
25
+ } | null): string;
26
+ /**
27
+ * A custom page whose content is a site: an iframe in the view, the site's origin allowed as a frame (MCP Apps CSP
28
+ * `frameDomains`). A page on the app's own site (`embed`) is opened signed in: the view asks the app for a ticket
29
+ * (`clegra_embed`, for this document's origin) over the host's bridge and posts it into the frame (spec §5.1).
30
+ * A page on another site is framed as it is.
31
+ */
32
+ export declare function urlPageHtml(title: string, url: string, embed: {
33
+ tool: string;
34
+ page: string;
35
+ } | null): string;