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 be npm 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
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).