@gloocan/cat-inspector 0.1.1 → 0.1.2
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 +166 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# 🐱 Cat Inspector SDK
|
|
2
|
+
|
|
3
|
+
<img
|
|
4
|
+
src="https://cat-inspector.gloocan.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flogo3.abd05647.png&w=1080&q=75"
|
|
5
|
+
alt="logo"
|
|
6
|
+
/>
|
|
7
|
+
|
|
8
|
+
**Welcome!** This is the official home of the TypeScript SDK that connects your backend to QA and inspection tooling—safely, deliberately, and without handing the internet a remote-code-execution button. ✨
|
|
9
|
+
|
|
10
|
+
The published package is `**@gloocan/cat-inspector`**. All source you can build and ship lives under `**[ts/](./ts/)`**.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 👋 New here? Start calm
|
|
15
|
+
|
|
16
|
+
**Cat Inspector** is a **host-side library**: you drop it into **your** Node.js app. It does **not** replace your product, your API design, or your database.
|
|
17
|
+
|
|
18
|
+
Think of it as a friendly gatekeeper:
|
|
19
|
+
|
|
20
|
+
- 🎯 You choose **which** functions may be discovered and invoked by QA tools.
|
|
21
|
+
- 📋 You attach **metadata** (names, parameters, return hints, optional JSON Schema) so generic UIs can build forms and checks.
|
|
22
|
+
- 🔒 Only what you **register** is on the menu—nothing else gets exposed by accident.
|
|
23
|
+
|
|
24
|
+
**You do not need the whole map on day one.** Most teams start with three ideas:
|
|
25
|
+
|
|
26
|
+
1. **Registration** — how functions join the catalog
|
|
27
|
+
2. **Express** — how those units line up with your HTTP world
|
|
28
|
+
3. **One transport** — how a QA client says hello (WebSocket, Socket.IO, bridge—pick what you use)
|
|
29
|
+
|
|
30
|
+
Everything beyond that is **bonus depth** when you need it. 🌱
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 🗂️ How `sdk/` fits this repo
|
|
35
|
+
|
|
36
|
+
This monorepo is bigger than the SDK (think **frontend**, **backend**, deploy recipes, examples). The `**sdk/`** folder is the **canonical home** for Cat Inspector:
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
| Path | What you’ll find |
|
|
40
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| 📄 `[README.md](./README.md)` *(this file)* | Friendly orientation—perfect first stop for humans. |
|
|
42
|
+
| 📦 `[ts/](./ts/)` | The real **npm package**: `package.json`, `src/`, tests, `PROTOCOL.md`, and `[ts/docs/](./ts/docs/)`. |
|
|
43
|
+
| 🧠 `[ts/src/](./ts/src/)` | Implementation; the **public API** is whatever `[ts/src/index.ts](./ts/src/index.ts)` exports. |
|
|
44
|
+
| 🏗️ `[ts/dist/](./ts/dist/)` | Build output from `npm run build` (publishable; often git-ignored). |
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
> 💡 **Consuming from npm?** You only need the package name + docs—you don’t have to clone the whole repo unless you want examples or contributions.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 🎪 What it *is*
|
|
52
|
+
|
|
53
|
+
Backend devs **register** hand-picked functions (handlers, services, little modules) as **named, typed, inspectable units**. QA clients get a **catalog**—stable ids, parameters, return metadata, optional tags—and can drive **forms + assertions** instead of shipping bespoke test code for every app.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 🚀 What it’s *for*
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
| Goal | Why it feels good |
|
|
61
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| 🛡️ **Controlled surface** | Pick entry points that are safe and meaningful to call from tooling—not “whatever was imported.” |
|
|
63
|
+
| 🤖 **Machine-friendly descriptions** | Schemas, labels, type hints keep QA UIs generic across products. |
|
|
64
|
+
| 🔌 **Authorized clients** | Embedded WebSocket, optional Socket.IO, remote bridge—listing and invoke stay under **your** process and rules. |
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
**Typical host:** a **Node.js / Express** (or similar) service where your real business logic already lives. ☕
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 🧩 Main areas at a glance
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
| Area | Role |
|
|
75
|
+
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| 🏷️ **Registration** | `@Cat`, `cat`, `catModule`, class/service helpers, instance registration → catalog entries. |
|
|
77
|
+
| 📡 **Bootstrap & metadata** | Load/merge catalog + bootstrap data; optional storage-backed bits so tools see one coherent picture. |
|
|
78
|
+
| 🚂 **Express** | Pipelines, correlation, optional HTTP bridge—meet your routes where they already are. |
|
|
79
|
+
| ⚡ **RPC surface** | Invoke by id with structured results/errors—no ad-hoc “run anything” scripting. |
|
|
80
|
+
| 🌐 **Transports** | WebSocket server, remote bridge, Socket.IO subpath export when you need it. |
|
|
81
|
+
| ✅ **Validation & policy** | JSON Schema, serialization limits, pre-invoke hooks, rate limits, audits. |
|
|
82
|
+
| 🎨 **Returns & labels** | `Return`, `Throw`, `ApiReturn` so tooling can tell labeled outcomes apart from plain values. |
|
|
83
|
+
| 🎁 **Optional extras** | Coverage helpers, OpenAPI export, uploads materialization, jobs/broadcasts, sessions—grab what you need. |
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 📖 Tiny glossary
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
| Term | In plain English |
|
|
92
|
+
| ------------------------- | -------------------------------------------------------------------------------------------- |
|
|
93
|
+
| **Host** | Your Node process running the SDK and your app code. |
|
|
94
|
+
| **Catalog** | The allowlisted set of registered units + metadata tools may see. |
|
|
95
|
+
| **Function id** | Stable string clients use when they invoke something specific. |
|
|
96
|
+
| **Inspector / QA client** | Another app or UI that talks to your host—not shipped inside this package. |
|
|
97
|
+
| **Protocol** | Versioned JSON + message families—see `[ts/PROTOCOL.md](./ts/PROTOCOL.md)` for the contract. |
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## ✅ Before you integrate (checklist vibes)
|
|
103
|
+
|
|
104
|
+
- **Node.js** + **npm** (or pnpm/yarn—your house, your rules).
|
|
105
|
+
- **TypeScript** in the host is typical; types ship with the package.
|
|
106
|
+
- **Peers:** `express` when you use Express helpers; `**minio`** / `**socket.io`** are optional—peek at `[ts/package.json](./ts/package.json)`.
|
|
107
|
+
- `**@Cat` decorators?** Turn on `**reflect-metadata`** + TS `**experimentalDecorators`** / `**emitDecoratorMetadata`** (details live in the docs linked below).
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 🗺️ Suggested reading order (snackable path)
|
|
112
|
+
|
|
113
|
+
1. **This README** — you’re almost done with step one. Nice. 🎉
|
|
114
|
+
2. `**[ts/docs/protocol-client.md](./ts/docs/protocol-client.md)`** — if you’ll build or wire a client.
|
|
115
|
+
3. `**[ts/docs/boostrap.md](./ts/docs/boostrap.md)`** — bootstrap-oriented notes (path matches the repository filename).
|
|
116
|
+
4. `**[ts/PROTOCOL.md](./ts/PROTOCOL.md)`** — wire truth; keep clients aligned with `**PROTOCOL_VERSION**`.
|
|
117
|
+
5. **[Nextra docs](../qa-test-doc/src/)** — long-form MDX. Run:
|
|
118
|
+
```bash
|
|
119
|
+
cd qa-test-doc/src && npm install && npm run dev
|
|
120
|
+
```
|
|
121
|
+
…then open **[http://localhost:3015](http://localhost:3015)** (default dev port).
|
|
122
|
+
6. **Runnable demo:** `[examples/cat-demo/backend](../examples/cat-demo/backend/README.md)` — Express + Socket.IO, real bootstrap, copy-paste energy. 🐾
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 📚 Doc map (who reads what)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
| Resource | Best for |
|
|
130
|
+
| -------------------------------------- | ---------------------------------- |
|
|
131
|
+
| `[ts/PROTOCOL.md](./ts/PROTOCOL.md)` | Wire compatibility detectives 🕵️ |
|
|
132
|
+
| `[ts/docs/](./ts/docs/)` | Day-to-day integrators |
|
|
133
|
+
| `[qa-test-doc/](../qa-test-doc/)` | Deep dives + searchable reference |
|
|
134
|
+
| `[ts/package.json](./ts/package.json)` | Scripts, `exports`, peers, version |
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 🛠️ Install & build (from a full clone)
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
cd sdk/ts
|
|
143
|
+
npm install
|
|
144
|
+
npm run build
|
|
145
|
+
npm test
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
**Consumers** add `**@gloocan/cat-inspector`** from your registry or workspace. Imports follow `**package.json` → `exports`** (main entry + optional `**@gloocan/cat-inspector/socket-io`** when published).
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## 🤝 Contributing
|
|
153
|
+
|
|
154
|
+
- Keep `**index.ts` exports** stable or clearly versioned—downstream clients will thank you. 🙏
|
|
155
|
+
- Under `sdk/ts`, run `**npm run typecheck`** and `**npm test`** before opening a PR.
|
|
156
|
+
- If behavior crosses the wire, update `**PROTOCOL.md`** plus `**ts/docs/**` or `**qa-test-doc/**` in the same breath when you can.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## 🌟 One-sentence summary
|
|
161
|
+
|
|
162
|
+
**Cat Inspector** is the **host-side SDK** that says *which* backend behavior is QA-visible, *how* tools should describe and validate it, and *how* authorized clients connect—while keeping the whole story explicit in **your** codebase.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
*Happy inspecting! 🐱✨*
|