Server SDK: @trowyn/server
TypeScript, no dependencies, ESM. Uses fetch and Web Crypto, so the same code runs on
Node 18+, Deno / Supabase Edge Functions, Cloudflare Workers and Bun.
Early access: the package isn't on npm yet. Install it from the tarball in the Trowyn repository (
sdk/packages/trowyn-server-0.1.0.tgz):npm install ./trowyn-server-0.1.0.tgz. Once published it will benpm install @trowyn/server.
import { Trowyn, TrowynError, verifyWebhook } from "@trowyn/server";
const trowyn = new Trowyn({ apiKey: process.env.TROWYN_API_KEY }); // trw_test_… / trw_live_…
trowyn.environment; // "test" | "live", from the key
Link a user's iPhone
const link = await trowyn.createLinkCode({ externalUserId: user.id, label: user.email });
// link.link_url → QR code or a link to send (Universal Link, opens Trowyn)
// link.code → typed fallback, e.g. "K7Q2P-9XFD3"
// link.id + link.client_token → hand to the widget to show progress
Add your TOTP enrollment as a backup code (added to the links locally, never sent to Trowyn):
const link = await trowyn.createLinkCode({ externalUserId: user.id, label: user.email, backupOtpauthUri: totpUri });
// or: withBackupCode(existingLink, totpUri)
// Show link.link_url only as a QR on a signed-in page: it now contains the TOTP secret.
Approve a sign-in
const approval = await trowyn.createApproval({
externalUserId: user.id,
appName: "Acme Portal",
ipAddress: req.ip, // optional, shown if your policy allows
location: "Austin, TX (approx.)", // optional
});
// Show approval.match_number on your page (or give the widget id, client_token, match_number).
const result = await trowyn.waitForApproval(approval.id, { timeoutMs: 180_000 });
if (result.status === "approved" && result.external_user_id === user.id) {
// sign in
}
waitForApproval polls getApproval (every 1.5 s by default) until the status isn't pending.
It returns denied and expired results instead of throwing; it throws only on errors, timeoutMs or
an aborted signal. In a web app you'll usually create the approval in one request, let the widget
show progress, and call getApproval(id) when the browser says it's done.
Webhooks
// Express: app.post("/webhooks/trowyn", express.raw({ type: "application/json" }), handler)
const event = await verifyWebhook(req.body /* raw Buffer or string */, req.get("trowyn-signature"), process.env.TROWYN_WEBHOOK_SECRET);
switch (event.type) { case "approval.approved": /* … */ break; }
Throws TrowynWebhookError on a bad, missing or stale (> 5 minutes) signature. Options:
{ toleranceSeconds }. signWebhookPayload(body, secret, t) is exported for your tests.
Errors
API errors throw TrowynError with status (HTTP status, 0 for network errors and timeouts) and
code (the API's error, e.g. no_linked_device, rate_limited, unauthorized).
try { await trowyn.createApproval({ externalUserId: id, appName: "Acme" }); }
catch (e) { if (e instanceof TrowynError && e.code === "no_linked_device") showLinkSetup(); else throw e; }
Options: new Trowyn({ apiKey, baseUrl?, fetch?, timeoutMs? = 15000 }). Responses are the API JSON
unchanged (snake_case); see the API reference. The constructor refuses to run in a
browser page.
Runtimes
// Supabase Edge Function / Deno
import { Trowyn } from "npm:@trowyn/server@0.1.0";
const trowyn = new Trowyn({ apiKey: Deno.env.get("TROWYN_API_KEY")! });
// Cloudflare Worker
import { Trowyn } from "@trowyn/server";
export default { async fetch(req: Request, env: { TROWYN_API_KEY: string }) {
const trowyn = new Trowyn({ apiKey: env.TROWYN_API_KEY });
/* … */ return new Response("ok");
} };
Full examples are in sdk/server/examples/ (Node HTTP server, Supabase Edge Function, Cloudflare Worker).