Node (server)

Create and manage links and send purchase events from your backend. Zero dependencies; authenticates with your secret key.

On this page 8
  1. Install
  2. Create the client
  3. Handle deep links
  4. Deferred deep links
  5. Events
  6. Verify a webhook
  7. Methods
  8. Common errors

One prompt · for your AI coding tool

Prompt
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

The full prompt, and the others

By hand · the install line

Terminal
npm install @straitlink/node@0.8.2

Then follow the steps below

You need
Node.js 18 or newer, and a secret key from Dashboard → Settings → Keys

Install

Install it from npm, pinned to a version:

Terminal
npm install @straitlink/node@0.8.2

Create the client

TypeScript
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.

A server doesn't open links: it creates them, and hears about every tap and open through webhooks (link.clicked, app.opened).

TypeScript
// 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 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

TypeScript
// 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.

Express
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 required or baseUrl must use https://. The constructor checks both. Plain http works only for localhost, 127.0.0.1 and ::1.
  • StraitError with status 401. The key is wrong, revoked, or a publishable key. The link API needs a secret key.
  • StraitError with status 402. A plan limit: .body.reason is links (new links this month) or clicks (taps this month). Links you already have keep working.
  • verifyWebhook: pass the raw request body. The body was already parsed as JSON. Use express.raw() on the webhook route instead of express.json().
  • Any other StraitError. .message is the API's error; every one is in the Error reference.