App links

links makes one link that opens the right screen wherever someone taps it, in your app on Android or iOS when installed and on the web when not, for invites, notifications and sign-in.

links:
  base: https://app.example.com
  routes:
    order: { web: "/orders/:id", app: "order/:id", params: [id] }

import { links } from "mainsdk";

const link = await links.create({ screen: "order", params: { id: order.id } });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { links } from "mainsdk";

describe("links", () => {
  it("links AC1 makes a link that names no screen or id", async () => {
    createTestApp({ main: "./main.yaml" });
    const link = await links.create({ screen: "order", params: { id: "ord_1" } });
    assert.ok(!link.url.includes("ord_1"));
    await assert.rejects(links.create({ screen: "invoice" }), { code: "MAIN-LINK-0002" });
  });

  it("links AC3 reports a revoked link", async () => {
    createTestApp({ main: "./main.yaml" });
    const link = await links.create({ screen: "order", params: { id: "ord_1" } });
    await links.revoke(link.id);
    assert.partialDeepStrictEqual(await links.resolve(link.url), { valid: false, reason: "revoked" });
  });
});

links:
  driver: getqr

Quick start

schema: 1
links:
  base: https://app.example.com
  routes:
    order: { web: /orders/:id, app: orders/:id, params: [id] }

"use server";
import { links } from "mainsdk";

export async function orderLink(orderId: string) {
  const link = await links.create({ screen: "order", params: { id: orderId } });
  return link.url;   // a getqr.id link that lands on https://app.example.com/orders/<id>
}

links.create() returns { id, url, qr, expiresAt, kind }. The URL names neither the screen nor the id. A screen you did not declare, or params that differ from the declared list, fail with MAIN-LINK-0002 before any request.

Configuration

links:
  base: https://app.example.com     # the app's own HTTPS origin; deep links land here
  default-expiry: 30d               # capped by share.max-expiry
  key: secret:LINKS_KEY             # keys the hash of a bound invite email
  routes:
    order: { web: /orders/:id, app: orders/:id, params: [id] }
    list:  { web: /lists/:id,  app: lists/:id,  params: [id] }
  apps:
    ios: { team-id: ABCDE12345, bundle-id: com.example.app }
    android: { package: com.example.app, sha256: ["14:6D:E9:…"] }
    store: { ios: "https://apps.apple.com/app/id123", android: "https://play.google.com/store/apps/details?id=com.example.app" }

Invite and link records live in the app's kv, scoped to the tenant. Links mint through share, so share settings (driver, key, max-expiry) apply: share.driver: local mints links in process in development.

Building it by hand

The SDK builds links for you from main.yaml. Call these only when you wire it by hand, for example in a test or a custom runtime.

What you get

You declare your screens once under links.routes. Every link is a share minted through getqr.id, so it expires, can be revoked and shows nothing of the screen or its params in the URL. Reach for it for invites, order notifications, sign-in links and anything you send that should land on a specific screen. A link grants nothing: whoever opens it still signs in and passes access.

Links in engagement messages

A reminder message carries a link as a {{link.<name>}} placeholder declared under notify.engagement.links. It is not a links route per person: engagement mints one share per journey, rung and variant through share (placement <journey>.<rung>.<variant>, mainsdk_kind: engagement), so no link identifies a person. Opens return as aggregate counts per variant (ADR-0056). Every producer's link, from auth.invites.create (mainsdk_kind: invite) to feeds, imports reports and the seal record page, goes through share; no module calls a getqr.id host itself.

Examples

Link in a message

Create the link when you send. The sender is your own code, such as notify.

import { links } from "mainsdk";

export async function shippedMessage(orderId: string) {
  const link = await links.create({ screen: "order", params: { id: orderId } }, { expiresIn: "14d" });
  return `Your order has shipped: ${link.url}`;
}

Resolve an incoming link

links.resolve() takes a request or a URL, either the getqr.id link or a URL on links.base. It returns the screen and params and never throws for an unknown URL.

import { links } from "mainsdk";

export async function GET(req: Request) {
  const target = await links.resolve(new URL(req.url).searchParams.get("u") ?? "");
  return Response.json(target);   // { kind, route, valid, reason? }
}

valid is false with reason of expired, revoked, used-up or unknown (then route is null).

Invite someone

An invite is a link that works for a number of uses and, if you bind an email, only for the signed-in person with that verified email. links.accept(req, token) needs a session, checks the invite and uses one up atomically. A used-up, expired, revoked or wrong-email invite fails with MAIN-LINK-0001 (410); a wrong email leaves the invite usable for the right person.

import { auth, links } from "mainsdk";

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req);
  const { id } = await params;
  const invite = await links.invite(
    { screen: "list", params: { id } },
    { email: "jane@example.com", uses: 1, expiresIn: "7d" },
  );
  return Response.json({ url: invite.url, expiresAt: invite.expiresAt });
}

Organisation invites stay in auth.invites. links.invite is for your own things: a list, a circle, a shared document. links.revoke(id) revokes the share and the invite record.

Sign in from an inbox

links.signIn({ email }) or ({ phone }) asks auth for a single-use token, wraps it in a 15-minute link and delivers it by email or, with via: "whatsapp", WhatsApp. It returns { sent: true, expiresAt } and never the link. An address with no account gets the same answer and nothing is sent, and every answer takes at least 400 ms, so speed never tells who has an account. It needs link in auth.methods (MAIN-LINK-0005 otherwise).

import { links } from "mainsdk";

export async function POST(req: Request) {
  const { email } = (await req.json()) as { email: string };
  const out = await links.signIn({ email }, { next: { screen: "order", params: { id: "ord_1" } } });
  return Response.json(out);   // { sent: true, expiresAt }
}

Association files

With links.apps set, links.route(req) answers /.well-known/apple-app-site-association (an applinks entry for <team-id>.<bundle-id> with one component per web route) and /.well-known/assetlinks.json (the package and fingerprints). It also serves /_mainsdk/store (the store page for the phone's platform) and /_mainsdk/auth/link (the sign-in redirect). It returns undefined for any other path.

import { links } from "mainsdk";

export async function GET(req: Request) {
  return (await links.route(req)) ?? new Response("Not found", { status: 404 });
}

Errors and checks

See check codes and errors.

Swapping drivers

links has no driver of its own; it uses the share driver. Set share.driver: local in development and getqr in production.

Testing

createTestApp runs links on the local share driver with no network.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { links } from "mainsdk";

describe("links", () => {
  it("links AC1 makes a link that names no screen or id", async () => {
    createTestApp({ main: "./main.yaml" });
    const link = await links.create({ screen: "order", params: { id: "ord_1" } });
    assert.ok(!link.url.includes("ord_1"));
    await assert.rejects(links.create({ screen: "invoice" }), { code: "MAIN-LINK-0002" });
  });

  it("links AC3 reports a revoked link", async () => {
    createTestApp({ main: "./main.yaml" });
    const link = await links.create({ screen: "order", params: { id: "ord_1" } });
    await links.revoke(link.id);
    assert.partialDeepStrictEqual(await links.resolve(link.url), { valid: false, reason: "revoked" });
  });
});

Security and privacy

• Links go through getqr.id, like every share link and QR code in a MainSDK app.
• Keep personal data out of params; use record ids your app resolves after sign-in. mainsdk check fails a route that declares a person-identifying param.
• An invite stores its token only as a SHA-256 digest and a bound email only as a keyed hash.
• Tokens appear only in the target URL handed to share, never in a log, an audit record or an error.

FAQ

How is this different from share()? share() gives someone read-only access to a link or file for a while. links opens a screen in your app; the person still signs in and goes through your normal checks.

Do I write the association files myself? No. links.route() generates them from links.apps. The passkey part (webcredentials) comes with the mobile sign-in spec.

Do deferred deep links survive an app install? No, and they are out of scope: they need device fingerprinting.

Next

• Share links and QR codes: private, expiring links to files and pages.
• Sign-in and sessions: the link method that links.signIn hands to.
• Notifications: send links on push, WhatsApp, SMS or email.
• Engagement journeys: {{link.<name>}} placeholders in reminder messages.