Node (server)
Create and manage links and send purchase events from your backend. Zero dependencies; authenticates with your secret key.
On this page 8
One prompt · for your AI coding tool
Create Strait links from this backend (Node.js, Next.js API routes or server actions).
Read https://straitlink.in/docs/sdks/node/ and follow it exactly. If anything here disagrees with that page, the page wins.
My link domain is https://<your-handle>.strait.link. My secret key (st_live_…, from Dashboard → Settings → Keys: https://app.straitlink.in/settings#keys) is in the environment variable STRAIT_SECRET_KEY.
Rules:
- Read the secret key only from the environment. Never write it into code, a .env file you commit, logs, or anything sent to a browser or app.
- This is server code only. In Next.js keep it in route handlers, server actions or a file that imports "server-only"; it must never reach a client component or a NEXT_PUBLIC_ variable.
- Handle StraitError: 409 means the slug is taken in my workspace, 402 means a plan limit (existing links keep working).
Steps:
1. Install the SDK with the command on that page.
2. Create one client in a server-only module with apiKey from process.env.STRAIT_SECRET_KEY and baseUrl https://strait.link.
3. Add a server function that creates a link for a record in this app (createLink with a slug, an https longUrl and tags) and returns the shortUrl the API sends back. For many links, use POST /v1/links/batch (up to 500 per call) instead of a loop.
4. Where this app records purchases, send them with sendEvent, passing clickId only when I have one (for example from an app.opened or install.matched webhook).
Finish by telling me exactly how to check it:
- the function returns a shortUrl on https://<your-handle>.strait.link/… and the link shows in Dashboard → Links
- grep -r st_live_ over the client bundle (for example .next/static) finds nothing- You need
- Node.js 18 or newer, and a secret key from Dashboard → Settings → Keys
Install
Install it from npm, pinned to a version:
npm install @straitlink/node@0.8.2Create the client
import { StraitClient } from '@straitlink/node';
const links = new StraitClient({
apiKey: process.env.SECRET_KEY!, // st_live_… from Dashboard → Settings → Keys
baseUrl: 'https://strait.link',
});
console.log((await links.listLinks()).length, 'links');You should see: a number and links, such as 0 links in a new workspace. A StraitError with status 401 means the key is wrong or is a publishable key.
Handle deep links
A server doesn't open links: it creates them, and hears about every tap and open through webhooks (link.clicked, app.opened).
// Create a link
const link = await links.createLink({
slug: 'launch',
longUrl: 'https://yourapp.com/launch',
tags: ['campaign'],
});
// List / update / deactivate
await links.listLinks();
await links.updateLink('launch', { longUrl: 'https://yourapp.com/launch-v2' });
await links.deleteLink('launch');Deferred deep links
Deferred matching happens in the app, through the app SDKs. Your server hears about each match as an install.matched webhook, with the link and the tap id (clickId).
Events
// Send a conversion / revenue event (no publishable key needed server-side)
await links.sendEvent({ event: 'purchase', value: 49.99, currency: 'USD' });
// Name the tap it came from, when you know it (for example from a webhook)
const clickId = '9a1c7e52-4b3d-4f8e-a6d1-0c2b5e7f9a34'; // clickId from an app.opened or install.matched webhook
await links.sendEvent({ event: 'purchase', value: 49.99, currency: 'USD', clickId });On a server nothing is remembered for you: sendEvent passes clickId through only when you give it. Use a tap id you received, such as clickId from an app.opened or install.matched webhook. The server keeps it only if it's a tap of your workspace; otherwise it drops the id and still records the event.
Failures throw a StraitError with .status and the parsed .body.
Verify a webhook
verifyWebhook (version 0.6.5 and later) checks that a webhook delivery came from Strait: the X-Strait-Signature HMAC of the timestamp and the raw body, compared in constant time, and no more than 5 minutes old. Pass the raw body, before any JSON parsing.
import express from 'express';
import { verifyWebhook } from '@straitlink/node';
const app = express();
app.post('/webhooks/strait', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyWebhook(req.body, req.headers, process.env.WEBHOOK_SECRET!)) return res.status(401).end();
const delivery = JSON.parse(req.body.toString('utf8')); // { id, event, createdAt, data }
// handle delivery.event / delivery.data …
res.status(204).end();
});It also takes a fetch Headers and a string body, for example verifyWebhook(await request.text(), request.headers, secret) in a route handler. To allow more clock drift, pass { toleranceSeconds: 600 }.
You should see: press Send test event next to the webhook in Dashboard → Settings → Webhooks, and the dashboard shows 204 from your server. With a wrong secret it shows 401.
Methods
| Method | Endpoint |
|---|---|
createLink(input) |
POST /v1/links |
listLinks() |
GET /v1/links |
updateLink(slug, fields) |
PATCH /v1/links/:slug |
deleteLink(slug) |
DELETE /v1/links/:slug |
sendEvent(input) |
POST /v1/event |
verifyWebhook(rawBody, headers, secret, opts?) |
No request: checks a webhook signature |
Full request and response details are in the REST API reference.
Common errors
StraitClient: apiKey is requiredorbaseUrl must use https://. The constructor checks both. Plainhttpworks only forlocalhost,127.0.0.1and::1.StraitErrorwithstatus401. The key is wrong, revoked, or a publishable key. The link API needs a secret key.StraitErrorwithstatus402. A plan limit:.body.reasonislinks(new links this month) orclicks(taps this month). Links you already have keep working.verifyWebhook: pass the raw request body. The body was already parsed as JSON. Useexpress.raw()on the webhook route instead ofexpress.json().- Any other
StraitError..messageis the API'serror; every one is in the Error reference.