<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Elido Engineering]]></title><description><![CDATA[Elido Engineering]]></description><link>https://elido.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sat, 21 Nov 2026 18:29:59 GMT</lastBuildDate><atom:link href="https://elido.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Short links and QR codes from code, then from Claude via MCP]]></title><description><![CDATA[You can click through a dashboard to shorten a link, or you can do it from a script. This tutorial covers the script route with the Elido SDKs for…]]></description><link>https://elido.hashnode.dev/short-links-and-qr-codes-from-code-then-from-claude-via-mcp</link><guid isPermaLink="true">https://elido.hashnode.dev/short-links-and-qr-codes-from-code-then-from-claude-via-mcp</guid><category><![CDATA[TypeScript]]></category><category><![CDATA[Python]]></category><category><![CDATA[golang]]></category><category><![CDATA[mcp]]></category><dc:creator><![CDATA[Oleksandr Tsoma]]></dc:creator><pubDate>Wed, 18 Nov 2026 16:50:19 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6afdd6297a35787d0bbb469d/63f91b9a-578b-450f-abae-813621093c8e.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>You can click through a dashboard to shorten a link, or you can do it from a script. This tutorial covers the script route with the Elido SDKs for TypeScript, Python and Go, then the assistant route: an MCP server that lets Claude Desktop or Cursor create links and read stats for you.</p>
<p>We ran every snippet below against the live API on a fresh free account, using the published packages (<code>@elido/sdk</code> 0.1.1, <code>elido-sdk</code> 0.1.0, <code>elido-go</code> v0.1.1, <code>@elido/mcp-server</code> 0.1.1). The outputs shown are the real ones from that run; swap in your own key and ids.</p>
<h2>What you need</h2>
<ul>
<li>A free Elido account. The free plan has 25 links and 500 tracked clicks a month (<a href="https://elido.app/en/pricing">pricing</a>).</li>
<li>An API key from the dashboard (API keys section). Keys start with <code>elido_</code>.</li>
<li>A workspace id. Every link call is scoped to one. The SDKs can list the workspaces your key sees, so you don't have to dig it out of the UI.</li>
<li>A domain id. A link has to live on a domain. The TypeScript SDK can fetch your workspace's primary redirect domain, which is a verified custom domain if you attached one, or the shared domain for your plan otherwise.</li>
</ul>
<img src="https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/9henxqno3eeq09mq67k2.png" alt="The API keys page in the Elido dashboard: one key named tutorial-demo, shown only by its prefix" style="display:block;margin:0 auto" />

<p>The API base is <code>https://api.elido.app</code> and auth is <code>Authorization: Bearer &lt;key&gt;</code>. The SDKs set that for you. Put the key in an environment variable, not in source:</p>
<pre><code class="language-bash">export ELIDO_API_KEY="elido_..."
</code></pre>
<h2>TypeScript</h2>
<pre><code class="language-bash">npm install @elido/sdk
</code></pre>
<p>The snippets use top-level <code>await</code>, so run them as ES modules: name the file <code>.mjs</code>/<code>.mts</code>, or set <code>"type": "module"</code> in <code>package.json</code>. Under CommonJS, <code>tsx</code> stops with <code>ERR_REQUIRE_ASYNC_MODULE</code>.</p>
<p>Start by finding your ids:</p>
<pre><code class="language-ts">import { ElidoApi } from "@elido/sdk";

const sdk = new ElidoApi({
  baseUrl: "https://api.elido.app",
  token: process.env.ELIDO_API_KEY!,
});

const { items } = await sdk.workspaces.list();
const workspaceId = items[0].id;

const domain = await sdk.workspaceDomains.primary(workspaceId);
console.log(workspaceId, domain.id);
// 74 1   (a fresh free workspace gets the shared domain f.elido.me)
</code></pre>
<p>Create a link. <code>domain_id</code> and <code>destination_url</code> are what the README example passes; <code>slug</code>, <code>title</code> and <code>tags</code> are optional:</p>
<pre><code class="language-ts">const link = await sdk.links.create(workspaceId, {
  domain_id: domain.id,
  destination_url: "https://example.com/landing",
  slug: "spring-sale",
  tags: ["spring-2026"],
});
console.log(link.slug);
</code></pre>
<p>Every POST gets an <code>Idempotency-Key</code> header automatically. If you run this from a cron job and want retries to be safe, pass your own stable key as the third argument:</p>
<pre><code class="language-ts">await sdk.links.create(workspaceId, input, { idempotencyKey: "job-2026-11-18" });
</code></pre>
<p>List links, filtered by tag if you like:</p>
<pre><code class="language-ts">const page = await sdk.links.list(workspaceId, { limit: 20, tags: ["spring-2026"] });
for (const l of page.items) console.log(l.id, l.slug, l.destination_url);
</code></pre>
<p>In the dashboard, the same links show up with their tag and click counts:</p>
<img src="https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/pcv6yayv7nxyojfvst6q.png" alt="The Links page listing six short links on f.elido.me tagged spring-2026, with 30-day click counts" style="display:block;margin:0 auto" />

<p>To walk everything, <code>links.iterate</code> pages for you:</p>
<pre><code class="language-ts">for await (const l of sdk.links.iterate(workspaceId)) {
  console.log(l.slug);
}
</code></pre>
<p>Click stats come from <code>analytics</code>. Dates are <code>YYYY-MM-DD</code>. <code>from</code> is inclusive and <code>to</code> is exclusive, so to include today, pass tomorrow's date. <code>linkId</code> narrows the series to one link. A link you created a minute ago has no clicks yet, so the output below is from a demo link that already had five:</p>
<pre><code class="language-ts">const series = await sdk.analytics.timeseries(workspaceId, {
  from: "2026-11-01",
  to: "2026-11-19",
  interval: "day",
  linkId: link.id,
});
console.log(series.items);
// [ { ts: '2026-11-18T00:00:00Z', count: 5 } ]
</code></pre>
<p>Days without clicks are left out of <code>items</code>, so fill the gaps yourself if you chart it.</p>
<p>There are also breakdowns such as <code>analytics.byCountry</code>, <code>byDevice</code> and <code>byReferrer</code>, plus <code>analytics.topLinks</code> for a ranking. On the demo workspace, after a handful of test clicks:</p>
<pre><code class="language-ts">const top = await sdk.analytics.topLinks(workspaceId, { from: "2026-11-01", to: "2026-11-19" });
console.log(top.items.slice(0, 2));
// [ { link_id: 592, slug: 'newsletter-nov-wi35', count: 5 },
//   { link_id: 593, slug: 'podcast-ep12-wi35', count: 4 } ]

const devices = await sdk.analytics.byDevice(workspaceId, { from: "2026-11-01", to: "2026-11-19" });
console.log(devices.items);
// [ { key: 'desktop', count: 14 } ]
</code></pre>
<h2>Python</h2>
<pre><code class="language-bash">pip install elido-sdk
</code></pre>
<p>The package is <code>elido-sdk</code> and the import is <code>elido</code>.</p>
<pre><code class="language-python">import os
from elido import Client

elido = Client(base_url="https://api.elido.app", token=os.environ["ELIDO_API_KEY"])

workspace_id = elido.workspaces.list()["items"][0]["id"]

link = elido.links.create(
    workspace_id,
    domain_id=1,  # your domain id
    destination_url="https://example.com/landing",
    tags=["spring-2026"],
)
print(link["slug"])  # 1nxR0z

page = elido.links.list(workspace_id, limit=20)
for row in page["items"]:
    print(row["id"], row["slug"])

series = elido.analytics.timeseries(
    workspace_id, from_="2026-11-01", to="2026-11-19", interval="day", link_id=link["id"]
)
print(series)  # {'items': [{'ts': '2026-11-18T00:00:00Z', 'count': 5}]}
</code></pre>
<p>Note <code>from_</code> with the trailing underscore, because <code>from</code> is a Python keyword. Results are plain dicts. The Python client has no domain lookup, so grab the domain id with the TypeScript snippet above or from the dashboard.</p>
<h2>Go</h2>
<pre><code class="language-bash">go get github.com/elidoapp/elido-go@latest
</code></pre>
<pre><code class="language-go">c, err := elido.New(elido.Options{
    BaseURL: "https://api.elido.app",
    Token:   os.Getenv("ELIDO_API_KEY"),
})
if err != nil {
    log.Fatal(err)
}
defer c.Close()

ctx := context.Background()

domains, err := c.Domains.List(ctx, 42) // 42 = your workspace id
// ...

link, err := c.Links.Create(ctx, 42, elido.CreateLinkInput{
    DomainID:       domains.Items[0].ID,
    DestinationURL: "https://example.com/landing",
    Tags:           []string{"spring-2026"},
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(link.Slug) // na9pN

ts, err := c.Analytics.Timeseries(ctx, 42, elido.TimeseriesOptions{
    From: "2026-11-01", To: "2026-11-19", Interval: "day", LinkID: link.ID,
})
if err != nil {
    log.Fatal(err)
}
for _, p := range ts.Points {
    fmt.Println(p.TS, p.Count)
}
// 2026-11-18T00:00:00Z 5
</code></pre>
<p>Import path is <code>github.com/elidoapp/elido-go/elido</code>. One catch: <code>Domains.List</code> returns only custom domains, so on a fresh workspace with none attached the list is empty. Use a domain id from the dashboard in that case. Use v0.1.1 or later; in v0.1.0 <code>Timeseries</code> always came back empty.</p>
<h2>QR codes</h2>
<p>The SDKs don't have a "generate a QR image" method. What the TypeScript SDK has is <code>links.getQRDesign</code>, <code>saveQRDesign</code> and <code>deleteQRDesign</code>, which store the styling for a link's QR code. To get the image itself from code, use the MCP server's <code>generate_qr</code> tool, covered next, or the QR page in the dashboard.</p>
<h2>Letting an AI assistant do it</h2>
<p>The MCP server exposes the same operations as tools. For Claude Desktop, edit <code>claude_desktop_config.json</code> (on macOS it lives in <code>~/Library/Application Support/Claude/</code>):</p>
<pre><code class="language-json">{
  "mcpServers": {
    "elido": {
      "command": "npx",
      "args": ["-y", "@elido/mcp-server"],
      "env": {
        "ELIDO_API_KEY": "elido_...",
        "ELIDO_WORKSPACE_ID": "42"
      }
    }
  }
}
</code></pre>
<p><code>ELIDO_API_KEY</code> is required. <code>ELIDO_WORKSPACE_ID</code> is optional: if you leave it out, the server uses the only workspace your key can see, so set it when the key has more than one. <code>ELIDO_API_BASE</code> overrides the API host and defaults to <code>https://api.elido.app</code>. Cursor takes the same block in <code>.cursor/mcp.json</code>. Restart the client and the tools appear.</p>
<p>There are five tools: <code>create_link</code>, <code>list_links</code>, <code>query_analytics</code>, <code>generate_qr</code> and <code>list_workspaces</code>. Three prompts and what they map to:</p>
<ol>
<li>"Shorten <a href="https://example.com/pricing">https://example.com/pricing</a> with the slug <code>pricing-q4</code> and tag it <code>q4</code>." Claude calls <code>create_link</code> with <code>destination_url</code>, <code>slug</code> and <code>tags</code>. If it passes no <code>domain_id</code>, the server takes the first domain from the workspace's domain list, and errors out asking for an explicit <code>domain_id</code> when that list is empty.</li>
<li>"Show clicks per day for the last two weeks in Europe/Berlin time." This is <code>query_analytics</code> with <code>from</code>, <code>to</code>, <code>interval: "day"</code> and <code>tz</code>. Pass a <code>link_id</code> to look at a single link.</li>
<li>"Make a 512px PNG QR code for link 118." That is <code>generate_qr</code> with <code>link_id</code>, <code>format: "png"</code> and <code>size: 512</code>. Use "list my last 10 links" first if you don't know the id; that is <code>list_links</code>.</li>
</ol>
<p>If a prompt misfires, look at which tool Claude actually called before blaming the model.</p>
<h2>Errors you will hit</h2>
<p>The TypeScript SDK throws <code>ElidoApiError</code> with <code>status</code> and <code>body</code>. Python raises <code>ElidoApiError</code> (with <code>status</code>, <code>body</code>, <code>message</code>) for non-2xx responses and <code>ElidoError</code> for transport failures. Go returns <code>*elido.APIError</code> with <code>Status</code>, <code>Message</code> and <code>Body</code>; check it with <code>errors.As</code>.</p>
<pre><code class="language-ts">import { ElidoApiError } from "@elido/sdk";

try {
  await sdk.links.create(workspaceId, input);
} catch (err) {
  if (err instanceof ElidoApiError &amp;&amp; err.status === 409) {
    // pick another slug
  } else {
    throw err;
  }
}
</code></pre>
<p>Branch on the HTTP status, not on a code string. Today the body carries only a human-readable message; reusing a slug on the same domain returned exactly this in all three SDKs:</p>
<pre><code class="language-plaintext">409 {"error": "slug already exists for this domain"}
</code></pre>
<p>A 400 means the input failed validation; log the <code>error</code> message, it says which field. On a 429, back off before retrying, and honour <code>Retry-After</code> when the response includes it.</p>
<p>In the MCP server, a missing <code>ELIDO_API_KEY</code> prints a warning at start and every tool call then fails, so check that first if nothing works.</p>
<h2>Where to go next</h2>
<p>Full reference is at <a href="https://elido.app/docs">elido.app/docs</a>. The SDKs are MIT licensed: <a href="https://github.com/elidoapp/elido-js">elido-js</a>, <a href="https://github.com/elidoapp/elido-python">elido-python</a>, <a href="https://github.com/elidoapp/elido-go">elido-go</a>, and the <a href="https://github.com/elidoapp/mcp-server">MCP server</a>.</p>
<p>Elido is a hosted link shortener with custom domains, QR codes and click analytics, built EU-first: <a href="https://elido.app">elido.app</a>.</p>
]]></content:encoded></item></channel></rss>