@brickkit/core 0.0.0-stage → 0.2.0

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.
package/README.md CHANGED
@@ -1,3 +1,92 @@
1
- # Temporary Holding Version
1
+ # @brickkit/core
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Core engine primitives for the Brick-TS framework: typed services, actions,
4
+ resources, databases (SQLite/Postgres via Drizzle), secrets, and pub/sub —
5
+ all validated with TypeBox and runnable on Bun or Node.
6
+
7
+ ```sh
8
+ bun add @brickkit/core drizzle-orm postgres
9
+ ```
10
+
11
+ ```ts
12
+ import { defineDatabase } from "@brickkit/core";
13
+ import { pgTable, text } from "@brickkit/core/pg";
14
+
15
+ const pages = pgTable("pages", {
16
+ id: text("id").primaryKey(),
17
+ title: text("title").notNull(),
18
+ });
19
+
20
+ export const db = defineDatabase({
21
+ engine: "postgres",
22
+ tables: { pages },
23
+ url: process.env.DATABASE_URL!,
24
+ });
25
+ ```
26
+
27
+ Bun-only APIs are lazy-loaded, so the package imports cleanly under
28
+ strict Node ESM too. Source: <https://github.com/Chandraprakash-Darji/brick>.
29
+
30
+ ## Typed client
31
+
32
+ `@brickkit/core/client` (also re-exported from the package root) offers an
33
+ Eden-style HTTP client inferred from your contract type — no OpenAPI codegen:
34
+
35
+ ```ts
36
+ import { createBrickClient } from "@brickkit/core/client";
37
+ import type { AppServer } from "./server"; // type-only: never bundled
38
+
39
+ const api = createBrickClient<AppServer>({ baseUrl: "http://localhost:4000" });
40
+ const pages = await api.page.list({ limit: 10 });
41
+ ```
42
+
43
+ See `www/content/docs/(brick)/typed-client.mdx` for the contract-first setup
44
+ (`defineAppContract` + `brickFromContract`), routing, and error handling.
45
+
46
+ ## MCP tools
47
+
48
+ Define tools like actions, with typed input/output schemas and inline metadata:
49
+
50
+ ```ts
51
+ import {
52
+ defineService,
53
+ createMcpRegistry,
54
+ createMcpHandler,
55
+ t,
56
+ } from "@brickkit/core";
57
+
58
+ const crm = defineService("crm");
59
+ const whoami = crm.tool({
60
+ name: "crm_whoami",
61
+ title: "View Connected CRM Account",
62
+ annotations: { readOnlyHint: true },
63
+ input: t.Object({}),
64
+ output: t.String(),
65
+ authorize: ({ user }) => !!user?.id,
66
+ execute: ({ ctx }) => ctx.user.id,
67
+ });
68
+
69
+ const registry = createMcpRegistry({ services: [crm] });
70
+ registry.listTools();
71
+ await registry.callTool("crm_whoami", {}, { user: { id: "user_1" } });
72
+
73
+ const handleMcp = createMcpHandler({
74
+ registry,
75
+ serverInfo: { name: "crm", version: "1.0.0" },
76
+ });
77
+ // After your app authenticates a request:
78
+ // return handleMcp(request, { user: { id: verifiedSubject } });
79
+ ```
80
+
81
+ Tools use action validation, authorization, and service context. They are stored
82
+ separately from HTTP actions and stay out of routes and OpenAPI by default,
83
+ including when a service or tool is referenced in `brickFromContract`. Add
84
+ `http: true` to a tool definition, or register it with `crm.action(whoami)`, to
85
+ expose it over HTTP as well.
86
+
87
+ The registry accepts `services` and/or an explicit `tools` array, rejects duplicate
88
+ names, and reads annotations directly from definitions. The handler is a
89
+ stateless POST JSON-RPC helper for initialize, ping, tools/list, and tools/call;
90
+ notifications receive an empty 202 response. Authentication and mounting remain
91
+ in your app. Its default protocol version is `2025-06-18`, following the
92
+ [MCP tools specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).