@hotfusion/modeller 0.0.2 → 0.0.3

package/docs/UTILITIES.md

@@ -0,0 +1,111 @@
+# Utilities
+
+Helpers exported from `@hotfusion/modeller` and from `src/utils`.
+
+> [← Back to README](../README.md)
+
+---
+
+## Public exports
+
+| Export    | Purpose                                                                |
+|-----------|------------------------------------------------------------------------|
+| `Bundler` | Rollup-based bundler for shipping client code (TS, JSON, LESS, terser).|
+| `KeyGen`  | System-wide secret generator.                                          |
+| `Adapter` | Base class for persistence — extend to plug in a backing store.        |
+
+---
+
+## `Bundler`
+
+A Rollup wrapper preconfigured for the Modeller stack. Bundles TypeScript, inlines JSON, compiles LESS via `rollup-plugin-postcss`, supports `@rollup/plugin-replace` for build-time substitutions, and minifies with terser.
+
+```ts
+import { Bundler } from '@hotfusion/modeller';
+
+const result = await Bundler.bundle({
+    entry  : 'src/client/index.ts',
+    output : 'dist/client.js'
+});
+```
+
+Use it for shipping client bundles served by the [Server layer](./SERVER.md), or for any pre-built artifact you want to expose at runtime.
+
+---
+
+## `KeyGen`
+
+```ts
+import { KeyGen } from '@hotfusion/modeller';
+
+const secret = KeyGen.getSystemSecret();              // → hex string
+const bytes  = KeyGen.getSystemSecret('uint8Array');  // → Uint8Array
+```
+
+`getSystemSecret()` returns a stable 32-byte secret. On first call it generates one and caches it to disk (`_secret.key`); subsequent calls return the same value. Use it as the JWT signing key, the session secret, or wherever a stable per-installation secret is needed.
+
+`KeyGen.generateSecret(false)` returns a fresh random secret each time — use this for one-off keys (per-document encryption, single-use tokens).
+
+---
+
+## `Adapter`
+
+Base class for persistence. See the full contract in the [Core layer doc](./CORE.md#adapter).
+
+```ts
+import { Adapter } from '@hotfusion/modeller';
+
+class MyAdapter extends Adapter {
+    async sync(id, doc) { /* persist */ }
+    async pull()        { /* return docs */ return []; }
+}
+```
+
+---
+
+## Internal utilities
+
+These live in `src/utils` and aren't re-exported from the package root, but are stable and safe to import directly.
+
+### `encrypt` / `decrypt`
+
+AES-256-GCM wrappers using a `Uint8Array` secret.
+
+```ts
+import { encrypt, decrypt } from '@hotfusion/modeller/dist/utils/encryption';
+
+const hash  = await encrypt('plaintext', secretBytes);
+const plain = await decrypt(hash,        secretBytes);
+```
+
+Pair with `KeyGen.getSystemSecret('uint8Array')` for the secret.
+
+### `signJWT` / `decodeJWT`
+
+`jose`-backed JWT helpers.
+
+```ts
+import { signJWT }   from '@hotfusion/modeller/dist/utils/sign-jwt';
+import { decodeJWT } from '@hotfusion/modeller/dist/utils/decode-jwt';
+
+const token  = await signJWT(payload, secret, { exp: '1h' });
+const claims = decodeJWT(token);
+```
+
+### `request`
+
+Minimal `fetch` wrapper used internally by the connector. Returns the parsed body, throws on non-2xx.
+
+```ts
+import { request } from '@hotfusion/modeller/dist/utils/request';
+
+const data = await request('https://api.example.com/x', { method: 'GET' });
+```
+
+### `ObjectCollection`
+
+A typed `Map`-with-extras used internally for keyed collections. Useful when you need a `Map` plus filtering / iteration helpers.
+
+---
+
+> **Related:** [Core →](./CORE.md) · [Errors →](./ERRORS.md)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@hotfusion/modeller",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "exports": {