Etymolt Brand Check — Bubble plugin

Official Bubble.io plugin for the Etymolt brand-name clearance API. Drop the Clear a name workflow action into any Bubble workflow to get a cryptographically signed clearance verdict against USPTO, EUIPO, and UKIPO trademarks plus live domain and social-handle availability.

• Workflow action: Clear a name — inputs a name (and optional business description / Nice classes), returns a signed EVP/1.x verdict envelope with per-jurisdiction status, domain state, and open handles.
• Visual element: Etymolt Verdict Card — a drop-in color-coded card (green PROCEED, amber PROCEED_STRATEGIC, red ABANDON) that renders the verdict for a user and links to www.etymolt.com/verify for third-party cryptographic verification.
• API key: set once in the plugin config, used by every workflow action. Never exposed to the browser — all HTTP happens server-side in the Bubble sandbox.

Price: $0.25 per verdict (billed to your Etymolt account, not through Bubble). See etymolt.com/pricing.

License: Apache-2.0.

---

Install

There are two ways to install this plugin in a Bubble app.

From the Bubble marketplace (recommended)

Coming soon — submission pending. Once listed, install via Plugins → Add plugins → search "Etymolt".

From this repository (private / dev install)

1. In your Bubble app, go to Plugins → Add plugins → Contribute a new plugin.
2. Point the new plugin at this repository as its source of truth. The plugin.json at the repo root describes the manifest; each actions/* and elements/* subdirectory ships one Bubble capability.
3. Save. The plugin is now installed only in this app.

Publishing to the marketplace is an operator step that requires the Bubble editor UI — see OPERATOR_ACTION_CARD_FINAL.md in the internal etymolt-deploy workspace.

---

Configure

Open Plugins → Etymolt Brand Check and fill in:

Field	Default	Description
Etymolt API Key (required)	—	Your Etymolt API key. Get one at etymolt.com/dashboard. Stored server-side as a secret_key.
API Base URL	https://api.etymolt.com	Override for staging / self-hosted. Leave blank for production.
Default Nice classes	9,42	Comma-separated Nice classes used when the workflow action omits them. 9 = software, 42 = SaaS/design services.

Once set, every workflow that fires the Clear a name action reuses the key — you don't need to re-paste it per action.

---

Use the workflow action

Clear a name (Etymolt) takes three inputs and produces twenty outputs.

Inputs

Field	Required	Notes
Name	yes	The brand or product name to clear.
Business description	no	One-line description (e.g. dev tools SaaS). Improves class scoping. Strongly recommended.
Nice classes	no	Comma-separated, e.g. 9,42. If blank, the plugin default (9,42) applies.

Outputs

Output	Type	Notes
Verdict	text	PROCEED / PROCEED_STRATEGIC / ABANDON
Score	number	0-100 clearance confidence
Verdict ID	text	e.g. v_5506abc0d1e2f3 — pass this (or the JSON) to the Verdict Card element
Signature key ID	text	e.g. etymolt-1779085662 — the Ed25519 public key that signed this verdict
Signature (base64)	text	Raw signature bytes; used for offline verification
Issued at	date	Signing timestamp
Valid until	date	Re-verify after this
Disclaimer	text	Plain-language perishability disclaimer to render next to the verdict
Findings	list of texts	1-N plain-language findings from the check
Verify URL	text	https://www.etymolt.com/verify#<verdict_id>
US / EU / UK trademark status	text	clear / caution / conflict / unknown
Primary domain	text	e.g. klasp.com
Domain status	text	available / registered_active / registered_parked / unknown
Open handles	list	Platforms where the handle is available
Taken handles	list	Platforms where the handle is taken
Full verdict (JSON)	text	Signed envelope as a JSON string — pipe into the Verdict Card
Error code	text	Empty on success. Non-empty examples: missing_api_key, invalid_api_key, quota_exceeded, rate_limited, http_5xx
Error message	text	Human-readable failure detail

Error handling

The action never throws to Bubble — a failed HTTP call still returns a result object with Verdict empty and Error code / Error message populated. Branch on Result of step 1's Error code is empty in your workflow to route successes vs. errors.

---

Use the Verdict Card element

Drop Etymolt Verdict Card from the visual-elements toolbox onto any page or repeating group.

Properties

Property	Type	Notes
Verdict JSON	text	Full signed verdict envelope as a JSON string. Typically piped from the "Clear a name" action's Full verdict (JSON) output. Takes precedence over Verdict ID.
Verdict ID	text	Just the ID (e.g. v_5506…). Renders a compact placeholder plus a "Verify this verdict" link that opens the etymolt.com/verify widget with the ID pre-loaded.
Show signature details	checkbox	Default on. Renders a footer with the signing key ID and the verify link.
Show findings	checkbox	Default on. Renders the top 3 findings as a bulleted list.
Compact mode	checkbox	Renders a shorter card — useful in lists.

Exposed states

The card publishes: verdict, score, verdict_id, signature_key_id, name, issued_at, valid_until, verify_url, loaded, error. Bind any of these to other elements on the page.

Events

• verdict_loaded — fires when a verdict finishes rendering.
• verify_clicked — fires when the user clicks the "Verify this verdict" link.
• load_error — fires when the verdict JSON is malformed.

---

Example — end-to-end

See examples/workflow-example.md for a step-by-step walkthrough:

1. A page with a name input + description input + button.
2. A button workflow that fires Clear a name, stashes the full verdict JSON on a page-level custom state, and displays an alert on error.
3. A Verdict Card bound to that custom state.

A rendered mock of the card (mimicking the real design canvas preview) lives at examples/verdict-card-example.png.

---

Architecture

etymolt-bubble/
├── plugin.json                     Bubble plugin manifest + config fields
├── actions/
│   └── clear_a_name/
│       ├── action.json             Inputs + outputs the app-builder sees
│       └── server.js               Node.js runner (Bubble server sandbox)
├── elements/
│   └── verdict_card/
│       ├── element.json            Properties + states + events
│       ├── initialize.js           Runs once per element instance
│       ├── update.js               Runs on every property change
│       ├── preview.js              Editor design-canvas mock
│       └── styles.css              Self-contained CSS (also inlined in initialize.js)
├── shared/
│   └── api-client.js               HTTP + payload helpers used by every action
├── examples/
│   ├── workflow-example.md         Step-by-step wiring guide
│   └── verdict-card-example.png    Placeholder screenshot (post-publish real)
├── LICENSE                         Apache-2.0
└── README.md                       This file

Server sandbox

Every workflow action runs in Bubble's Node.js server sandbox. The runner gets context.request (Bubble's HTTP client) and context.keys (the plugin config values, including the API key). No browser code ever sees the API key.

Verifiable verdicts

Every verdict returned by the API carries an Ed25519 signature. The public keys are published at https://www.etymolt.com/.well-known/verdict-keys.json; any verifier (the browser widget at /verify, the Python or TypeScript SDKs, or your own code) can independently check the signature without contacting Etymolt.

The plugin surfaces the raw signature_b64 and signature_key_id on every action output so you can round-trip signed verdicts into your Bubble database and re-verify them at any point.

Verdict enum

• PROCEED — the name is clear against every checked source; ship it.
• PROCEED_STRATEGIC — the name is clear but has one or more items the user should notice (near-collision, secondary jurisdiction gap, parked domain, etc.). The findings array explains what.
• ABANDON — a hard blocker was hit (registered trademark in a relevant class, exact-match famous mark, domain conflict). The findings array explains which.

---

Support

• Docs: etymolt.com/docs/integrations/bubble
• API reference: etymolt.com/docs
• Support: [email protected] or etymolt.com/support
• Issues: github.com/etymolt/etymolt-bubble/issues

---

License

Apache-2.0. See LICENSE.

Copyright © 2026 Etymolt Inc.