@ferscloud/fers-calculation-web 0.2.60 → 0.2.62

package/README.md

@@ -185,8 +185,35 @@ const mr = res.result.results.loadcases["…"].member_results["1"];
 
 Off by default to keep the payload lean; omitted from `member_results` when not requested.
 
+## Attribution
+
+Free-tier results carry an `attribution` object minted inside the solver.
+Premium results (solved with a valid solve token) do not, so the same code
+credits FERS on the free tier and white-labels on Pro:
+
+```ts
+import { fersAttributionHtml } from "@ferscloud/fers-calculation-web/badge";
+
+// "" when the result came back from a Pro solve.
+const credit = fersAttributionHtml(res);
+```
+
+`getFersAttribution`, `fersAttributionText` and `createFersBadge` are also
+exported. All of them accept the envelope, the parsed model or the results
+bundle, and all return nothing for a Pro result or an error envelope.
+
+On 0.2.61 this subpath resolved only under a bundler; plain Node ESM needed
+`/badge.js`. From 0.2.62 the package ships an `exports` map and both forms work
+everywhere.
+
+Using the free tier in an application? Please display the credit. It is the
+only thing the free tier asks of you.
+
 ## Links
 
-- [Full documentation & getting started](https://ferscloud.com/getting-started)
+- [Structural analysis in JavaScript](https://ferscloud.com/structural-analysis-javascript) — why run the solver client-side
+- [JavaScript documentation](https://ferscloud.com/docs/javascript) — bundler setup, error codes, types, solve tokens
+- [Full documentation](https://ferscloud.com/getting-started) — every route into FERS
+- [llms-full.txt](https://ferscloud.com/llms-full.txt) — the whole documentation in one fetch, for agents
 - [FERS Cloud](https://ferscloud.com)
-- [FERS_core Python package](https://pypi.org/project/fers-core/)
+- [FERS Python package](https://pypi.org/project/fers/) — `pip install FERS`

package/badge.d.ts

@@ -0,0 +1,33 @@
+/** Free-tier provenance stamp. Absent from Premium results. */
+export interface FersAttribution {
+  /** Always "FERS". */
+  generated_by: string;
+  /** Canonical product URL. */
+  url: string;
+  /** Engine version that produced the results. */
+  engine_version: string;
+  /** Always "free" — Premium results carry no attribution at all. */
+  tier: string;
+  /** Plain-text credit. */
+  text: string;
+  /** Ready-to-inject HTML anchor. */
+  html: string;
+}
+
+/**
+ * Find the attribution object in a solver envelope, a parsed model, or a
+ * results bundle. Returns null for Premium results and for error envelopes.
+ */
+export function getFersAttribution(input: unknown): FersAttribution | null;
+
+/** Ready-to-inject HTML anchor, or "" on Pro. */
+export function fersAttributionHtml(input: unknown): string;
+
+/** Plain-text credit, or "" on Pro. */
+export function fersAttributionText(input: unknown): string;
+
+/** A detached DOM element carrying the credit, or null on Pro. */
+export function createFersBadge(
+  input: unknown,
+  doc?: Document,
+): HTMLElement | null;

package/badge.js

@@ -0,0 +1,69 @@
+// Attribution helpers for @ferscloud/fers-calculation-web.
+//
+// Free-tier results carry an `attribution` object minted inside the solver;
+// Premium results (solved with a valid solve token) do not. Everything here
+// returns nothing when the field is absent, so the same code shows a credit on
+// the free tier and white-labels on Pro with no flag to set and no branch to
+// write.
+//
+// Deliberately framework-free: a solver package should not drag in React. Use
+// `fersAttributionHtml()` with your framework's raw-HTML escape hatch, or
+// `createFersBadge()` if you would rather be handed a DOM node.
+//
+// Shipped only with the browser package. The Node build is server-side, where
+// a badge has nothing to render into — read `attribution.text` directly there.
+
+/**
+ * Find the attribution object, accepting whichever shape you happen to hold:
+ * the solver envelope, the parsed model, or the results bundle itself.
+ * @returns {{generated_by: string, url: string, engine_version: string, tier: string, text: string, html: string} | null}
+ */
+export function getFersAttribution(input) {
+  if (!input || typeof input !== "object") return null;
+  // Envelope: { ok, result } — an error envelope has nothing to credit.
+  if ("ok" in input) return input.ok ? getFersAttribution(input.result) : null;
+  // Parsed model: { ..., results: ResultsBundle }
+  if (input.results) return getFersAttribution(input.results);
+  // Results bundle.
+  return input.attribution ?? null;
+}
+
+/** Ready-to-inject HTML anchor, or "" on Pro. */
+export function fersAttributionHtml(input) {
+  return getFersAttribution(input)?.html ?? "";
+}
+
+/** Plain-text credit, or "" on Pro. Use for text reports and console output. */
+export function fersAttributionText(input) {
+  return getFersAttribution(input)?.text ?? "";
+}
+
+/**
+ * Build a detached DOM element carrying the credit, or null on Pro.
+ * @param {object} input solver envelope, model, or results bundle
+ * @param {Document} [doc] defaults to the global document
+ * @returns {HTMLElement | null}
+ */
+export function createFersBadge(input, doc) {
+  const attribution = getFersAttribution(input);
+  if (!attribution) return null;
+
+  const d = doc ?? (typeof document !== "undefined" ? document : null);
+  if (!d) return null;
+
+  const el = d.createElement("span");
+  el.className = "fers-attribution";
+  el.style.fontSize = "12px";
+  el.style.opacity = "0.75";
+
+  const a = d.createElement("a");
+  a.href = attribution.url;
+  a.target = "_blank";
+  a.rel = "noopener";
+  // textContent, not innerHTML: the string comes from the solver, but building
+  // the node by hand keeps this helper injection-proof by construction.
+  a.textContent = attribution.text;
+
+  el.appendChild(a);
+  return el;
+}

package/fers-models.d.ts

@@ -211,6 +211,50 @@ export interface components {
          * @enum {string}
          */
         AnalysisOrder: "LINEAR" | "NONLINEAR";
+        /**
+         * @description Free-tier provenance stamp, attached to every result the free solver
+         *     produces and absent from Premium results.
+         *
+         *     Why it lives in the engine rather than in a JS wrapper: the tier is decided
+         *     inside the WASM module, by Ed25519-verifying a solve token against a public
+         *     key compiled into the binary (`wasm_bindings::verify_solve_token`). Anything
+         *     downstream of that boundary — a bundler config, a React component, a JSON
+         *     post-processing step — can be edited by whoever ships the page. Minting the
+         *     attribution here means the branded path is the default one, and removing it
+         *     means either holding the server's private key or patching and rebuilding a
+         *     WebAssembly binary.
+         *
+         *     It is not, and cannot be, an absolute guarantee: anything shipped to a
+         *     browser can ultimately be modified. It raises the cost of stripping
+         *     attribution from "delete a div" to "rebuild the engine", and the licence
+         *     carries the rest.
+         *
+         *     `html` and `text` are pre-rendered so a consumer can display the credit
+         *     without knowing anything about our brand. `fersAttributionHtml()` in
+         *     `@ferscloud/fers-calculation-web/badge` simply returns `attribution.html`,
+         *     and returns "" when the field is absent — so upgrading to Pro white-labels
+         *     with no code change.
+         */
+        Attribution: {
+            /**
+             * @description Engine version that produced the results. Mirrors
+             *     [`ResultsBundle::engine_version`].
+             */
+            engine_version: string;
+            /** @description Always "FERS". */
+            generated_by: string;
+            /** @description Ready-to-inject HTML anchor, for web UIs. */
+            html: string;
+            /** @description Plain-text credit, for console output, PDFs and text reports. */
+            text: string;
+            /**
+             * @description The tier this solve ran under. Only ever "free" — Premium results carry
+             *     no `attribution` object at all.
+             */
+            tier: string;
+            /** @description Canonical product URL. */
+            url: string;
+        };
         /**
          * @description A global coordinate axis.
          * @enum {string}
@@ -2355,6 +2399,7 @@ export interface components {
         };
         /** @description All analysis results: per load case, per load combination, unity-check results and the optional HTML report. */
         ResultsBundle: {
+            attribution?: null | components["schemas"]["Attribution"];
             buckling?: null | components["schemas"]["BucklingResults"];
             /**
              * @description Per-reference buckling runs, present only when `analysis.buckling`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferscloud/fers-calculation-web",
   "type": "module",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
@@ -12,16 +12,63 @@
     "fers_calculations.js",
     "fers_calculations_bg.js",
     "fers_calculations.d.ts",
-    "fers-models.d.ts"
+    "fers-models.d.ts",
+    "badge.js",
+    "badge.d.ts"
   ],
   "main": "fers_calculations.js",
-  "homepage": "https://ferscloud.com",
+  "homepage": "https://ferscloud.com/structural-analysis-javascript",
   "types": "fers_calculations.d.ts",
   "sideEffects": [
     "./fers_calculations.js",
     "./snippets/*"
   ],
+  "description": "Structural analysis FEM solver for beams, frames and trusses, compiled from Rust to WebAssembly. Runs in the browser or in Node with no server round-trip. Includes Eurocode EN 1993-1-1 steel checks.",
+  "keywords": [
+    "structural-analysis",
+    "structural-engineering",
+    "finite-element",
+    "finite-element-analysis",
+    "fem",
+    "fea",
+    "solver",
+    "beam",
+    "frame",
+    "truss",
+    "stiffness-matrix",
+    "bending-moment",
+    "shear-force",
+    "deflection",
+    "buckling",
+    "eurocode",
+    "en1993",
+    "steel-design",
+    "wasm",
+    "webassembly",
+    "rust",
+    "engineering",
+    "civil-engineering",
+    "cad"
+  ],
+  "bugs": {
+    "url": "https://github.com/Jeroen124/FERS_calculations/issues"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./fers_calculations.d.ts",
+      "default": "./fers_calculations.js"
+    },
+    "./badge": {
+      "types": "./badge.d.ts",
+      "default": "./badge.js"
+    },
+    "./fers-models": {
+      "types": "./fers-models.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
   }
 }