@ferscloud/fers-calculation 0.2.39 → 0.2.41

package/README.md

@@ -2,25 +2,82 @@
 
 High-performance structural engineering FEM solver compiled from Rust to WebAssembly. Runs entirely in the browser — no server round-trip per calculation.
 
+> This README covers both published packages: **`@ferscloud/fers-calculation`** (Node.js / server-side, `--target nodejs`) and **`@ferscloud/fers-calculation-web`** (browser / bundler, `--target bundler`). The API is identical; only installation and bundler setup differ.
+
 ## Installation
 
 ```bash
+# Browser apps (Vite, Next.js, webpack):
+npm install @ferscloud/fers-calculation-web
+# Node.js / server-side:
 npm install @ferscloud/fers-calculation
 ```
 
-## Quick start — free tier (up to 100 members)
+## Bundler setup (browser build)
+
+`@ferscloud/fers-calculation-web` is a WASM ES module that initialises via top-level `await`. Most bundlers need a one-time config:
+
+**Vite**
+
+```bash
+npm i -D vite-plugin-wasm vite-plugin-top-level-await
+```
 
 ```ts
-import init, { calculate_from_json } from "@ferscloud/fers-calculation";
+// vite.config.ts
+import wasm from "vite-plugin-wasm";
+import topLevelAwait from "vite-plugin-top-level-await";
 
-await init(); // load the WASM module once
+export default { plugins: [wasm(), topLevelAwait()] };
+```
 
-const result = calculate_from_json(JSON.stringify(myModel));
-const data = JSON.parse(result);
+**Next.js / webpack**
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ["@ferscloud/fers-calculation-web"],
+  webpack(config) {
+    config.experiments = { ...config.experiments, asyncWebAssembly: true };
+    config.output.environment = { ...config.output.environment, asyncFunction: true };
+    return config;
+  },
+};
+```
+
+The solver is synchronous and CPU-bound; for large models run it inside a Web Worker so the UI thread stays responsive. The Node.js package (`@ferscloud/fers-calculation`) needs no bundler config.
+
+## Quick start — free tier (up to 100 members)
+
+```ts
+import { calculate_from_json } from "@ferscloud/fers-calculation";
+
+// No init() call needed — the nodejs and bundler builds initialise the
+// WASM module automatically on import.
+const res = JSON.parse(calculate_from_json(JSON.stringify(myModel)));
+if (res.ok) {
+  const data = res.result; // displacements, member_results, unity_checks, …
+} else {
+  console.error(res.error.code, res.error.message);
+}
 ```
 
 No API key required. Works for any model with up to 100 members.
 
+## Response shape
+
+Every solver call returns a JSON **envelope**, so you `JSON.parse` once and branch on `ok` — you never have to sniff whether the returned string "looks like" an error:
+
+```jsonc
+// success
+{ "ok": true,  "result": { /* the full result document */ } }
+// failure (invalid model, over the member limit, malformed JSON, …)
+{ "ok": false, "error": { "code": "LimitExceeded",
+                          "message": "Number of members (250) exceeds allowed maximum of 100" } }
+```
+
+`error.code` is one of `InvalidJson`, `LimitExceeded`, `SolveError`, `InternalPanic`, `InternalSerialization`. The return value is **always** valid JSON.
+
 ## Authenticated tier — Pro (up to 10 000 members)
 
 Pro limits are unlocked by passing a short-lived signed token issued by the FERS Cloud server. The token is verified inside the WASM using an Ed25519 public key baked into the binary — it cannot be forged.
@@ -74,17 +131,16 @@ Same pattern works for Express, Deno, Bun, Cloudflare Workers, or any server-sid
 ### 3. Frontend: call the solver with the token
 
 ```ts
-import init, { calculate_from_json_with_token } from "@ferscloud/fers-calculation";
-
-await init();
+import { calculate_from_json_with_token } from "@ferscloud/fers-calculation";
 
 const { token } = await fetch("/api/solve-token").then(r => r.json());
 
-const result = calculate_from_json_with_token(JSON.stringify(myModel), token);
-const data = JSON.parse(result);
+const res = JSON.parse(calculate_from_json_with_token(JSON.stringify(myModel), token));
+if (!res.ok) throw new Error(`${res.error.code}: ${res.error.message}`);
+const data = res.result;
 ```
 
-If the token is missing, expired, or invalid, the solver falls back to the free 100-member limit — it never throws.
+If the token is missing, expired, or invalid, the solver falls back to the free 100-member limit — it never throws (a genuine solve failure comes back as `{ ok: false, error }`, not an exception).
 
 ## Tier comparison
 
@@ -99,6 +155,16 @@ If the token is missing, expired, or invalid, the solver falls back to the free
 
 Keep your `FERS_API_KEY` server-side only. The solve token it fetches is safe to pass to the browser — it is short-lived and cryptographically signed. Only FERS Cloud can issue valid tokens; the browser WASM can only verify them.
 
+## TypeScript types
+
+The browser package ships generated model types alongside the function signatures:
+
+```ts
+import type { FERS, ResultsBundle } from "@ferscloud/fers-calculation-web/fers-models";
+```
+
+`FERS` is the input model; `ResultsBundle` is the `result` payload of a successful envelope. Both are generated from the engine's OpenAPI schema, so they track the published version.
+
 ## Links
 
 - [Full documentation & getting started](https://ferscloud.com/getting-started)

package/fers_calculations.d.ts

@@ -3,6 +3,7 @@
 
 /**
  * Free-tier solver (100-member limit). Used when no valid solve token is present.
+ * Returns the JSON envelope described above.
  */
 export function calculate_from_json(json_data: string): string;
 
@@ -10,15 +11,19 @@ export function calculate_from_json(json_data: string): string;
  * Tier-aware solver. Verifies the Ed25519-signed solve token issued by the
  * FERS Cloud server; grants Premium limits (10 000 members) when the token
  * is valid and contains `"tier":"premium"`. Falls back to Free on any
- * failure — expired, malformed, or wrong signature.
+ * failure — expired, malformed, or wrong signature. Returns the JSON envelope.
  */
 export function calculate_from_json_with_token(json_data: string, solve_token: string): string;
 
+/**
+ * Parse (without solving) a model from a file path and return it as the JSON
+ * envelope: `{"ok":true,"result": <FERS JSON> }` or an error envelope.
+ */
 export function load_fers_from_file(path: string): string;
 
 /**
  * Re-render unity-check reports from already-solved results (no re-solve). Fills
  * each `rendered_report` from its check's `report_template` and rebuilds
- * `report_html`. Returns the error string on failure.
+ * `report_html`. Returns the JSON envelope.
  */
 export function render_reports_from_json(json_data: string): string;

package/fers_calculations.js

@@ -2,6 +2,7 @@
 
 /**
  * Free-tier solver (100-member limit). Used when no valid solve token is present.
+ * Returns the JSON envelope described above.
  * @param {string} json_data
  * @returns {string}
  */
@@ -25,7 +26,7 @@ exports.calculate_from_json = calculate_from_json;
  * Tier-aware solver. Verifies the Ed25519-signed solve token issued by the
  * FERS Cloud server; grants Premium limits (10 000 members) when the token
  * is valid and contains `"tier":"premium"`. Falls back to Free on any
- * failure — expired, malformed, or wrong signature.
+ * failure — expired, malformed, or wrong signature. Returns the JSON envelope.
  * @param {string} json_data
  * @param {string} solve_token
  * @returns {string}
@@ -49,6 +50,8 @@ function calculate_from_json_with_token(json_data, solve_token) {
 exports.calculate_from_json_with_token = calculate_from_json_with_token;
 
 /**
+ * Parse (without solving) a model from a file path and return it as the JSON
+ * envelope: `{"ok":true,"result": <FERS JSON> }` or an error envelope.
  * @param {string} path
  * @returns {string}
  */
@@ -71,7 +74,7 @@ exports.load_fers_from_file = load_fers_from_file;
 /**
  * Re-render unity-check reports from already-solved results (no re-solve). Fills
  * each `rendered_report` from its check's `report_template` and rebuilds
- * `report_html`. Returns the error string on failure.
+ * `report_html`. Returns the JSON envelope.
  * @param {string} json_data
  * @returns {string}
  */
@@ -93,10 +96,10 @@ exports.render_reports_from_json = render_reports_from_json;
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_now_d2e0afbad4edbe82: function() {
+        __wbg_now_86c0d4ba3fa605b8: function() {
             const ret = Date.now();
             return ret;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferscloud/fers-calculation",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Jeroen124/FERS_calculations.git"