Share links and QR codes

share turns a link or a file into a private, expiring, read-only getqr.id link and QR code, with no personal data in the URL.

A share link never authorises a write. Reach for it when a user shares a report, a file, a profile card or an invite. Every share sheet, QR code and link page shows "Powered by getqr.id", and no app builds its own sharer or shortener.

You share something that already has an address: a url (a page of your app that checks access when it opens), a file's FileRef from files, an uploadId, a getqr.id cardId, the signed-in person's own contact, or a whatsapp number. A bare database record is not a resource; share the URL of the page that shows it.

share:
  driver: getqr
  key: secret:GETQR_API_KEY
  default-expiry: 7d
  max-expiry: 90d
app:
  url: https://acme.dev                # public origin; default share.origin of the local driver

import { share } from "mainsdk";

const { url, qr } = await share(order, { expiresIn: "7d", access: "read" });

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

describe("share", () => {
  it("files-share AC5 expires a link after its window", async () => {
    const testApp = createTestApp({ main: "./main.yaml" });
    const link = await share({ url: "https://app.example.com/reports/r1" }, { expiresIn: "7d" });
    assert.ok(!link.url.includes("reports"));          // nothing of the target is in the URL
    testApp.clock.advance("8d");
    assert.equal((await share.get(link.id)).status, "expired");
  });
});

share:
  driver: getqr

Quick start

share needs no block of its own when files uses the getqr driver: it reuses that key. Without files on getqr, set share.key. In development, share.driver: local mints links in process with no account.

files:
  driver: getqr
  key: secret:GETQR_API_KEY
share:
  default-expiry: 7d

import { auth, share } from "mainsdk";

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  await auth.require(req);
  const link = await share(
    { url: `https://app.example.com/reports/${id}`, title: "Q3 report" },
    { expiresIn: "7d", access: "read" },
  );
  return Response.json({ url: link.url, qr: link.qr, id: link.id, expiresAt: link.expiresAt });
}

The result is { url, qr, id, expiresAt }. The link's host is getqr.id, and it stops working at expiresAt or when you revoke it. Keep id to revoke, extend or read counts later.

Configuration

Every key lives under share:.

share:
  driver: getqr          # getqr (default) | local (development and tests only)
  key: secret:GETQR_API_KEY
  default-expiry: 7d     # expiry when a call passes no expiresIn
  max-expiry: 30d        # longest expiry a call may ask for
  track:
    analytics: false     # whether track: true is allowed to count opens

Overlays by market

A market can tighten expiry without touching code:

share:
  max-expiry: 14d

See main.yaml for overlay order and merge rules.

What you get

Examples

Share sheet with QRCode

Make the link on the server, then show it with <QRCode/> from @getqr/react, which shows "Powered by getqr.id". Its props belong to @getqr/react. On the server, share.qr(id, { format, size }) returns the QR image as { type, bytes }.

"use server";
import { auth, share } from "mainsdk";

export async function shareReport(req: Request, reportId: string) {
  await auth.require(req);
  const { url } = await share(
    { url: `https://app.example.com/reports/${reportId}` },
    { expiresIn: "7d" },
  );
  return url;
}

"use client";
import { QRCode } from "@getqr/react";

export function ShareSheet({ url }: { url: string }) {
  return <QRCode value={url} size={256} download />;
}

Share a file

Pass the FileRef that files.upload() returned. The holder gets read-only access for the expiry window. A file on the getqr.id driver is shared as its getqr.id upload; a file on another store is shared through a short-lived signed URL.

"use server";
import { files, share } from "mainsdk";

export async function shareUpload(bytes: Uint8Array, userId: string) {
  const ref = await files.upload(bytes, { owner: { id: userId }, type: "application/pdf" });
  return share(ref, { expiresIn: "24h", access: "read" });
}

Extend, revoke and read open counts

share.revoke(id) stops a link at once. share.update(id, { extend: "3d" }) moves the end later, never past max-expiry from now; asking to keep a link forever fails with MAIN-SHARE-0010. share.stats() returns plain open counts, and needs consent: true from the person whose links they are (MAIN-SHARE-0004 otherwise).

import { auth, share } from "mainsdk";

export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req);
  const { id } = await params;       // the id you stored from share()
  await share.revoke(id);
  return new Response(null, { status: 204 });
}

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req);
  const { id } = await params;
  const stats = await share.stats(id, { consent: true, range: "7d" });
  return Response.json(stats);       // { opens, byDay, byCountry, byDevice }
}

share.get(id) returns one share (url, qr, expiresAt, status, opens). share.list({ status, limit, cursor }) returns a page of { items, next }; status is live, expired or removed.

React to opens

share.on(type, fn) handles a getqr.id event and returns an unsubscribe function. Events arrive through the getqr inbound webhook (set webhooks.inbound.getqr.secret) or, on the local driver, straight from the in-process getqr.id. The types are share.created, share.opened, share.expired, share.removed, share.reported, upload.scanned, placement.scanned and chat.started.

import { share } from "mainsdk";

export const stop = share.on("share.opened", (event) => {
  console.log("opened", event.id);
});

Campaigns and placements

A placement is the one kept link: a printed QR code or an ad link that stays live and is counted per placement. Create them in a campaign. share.placements.create(campaignId, rows) creates all rows or none (MAIN-SHARE-0011 lists each bad row).

import { share } from "mainsdk";

const campaign = await share.campaigns.create({ name: "Diwali", brand: "Acme" });
const { placements, printSheet } = await share.placements.create(campaign.id, [
  { slug: "flyer-a", name: "Flyer A", kind: "link", url: "https://app.example.com/offer" },
]);
const counts = await share.placements.list(campaign.id, { consent: true });
console.log(placements[0]?.qr, counts.totals.opens, printSheet);

A row with kind: "ad_link" (the default) needs a whatsapp: { phone } number in E.164 form. share.usage() returns your plan's share, open and storage use against its limits, and share.webhooks.create(url, events) registers a getqr.id webhook endpoint. share.webhooks.list() returns the endpoints you registered, each with its status (healthy, failing or disabled) and no secret.

share.campaigns.get(id) reads one campaign back. share.placements.get(id, { consent }) reads one placement, and share.placements.update(id, patch) changes its name, url, whatsapp number or spend ({ inr, results, label? }); a placement's QR code never changes, so a printed sheet stays valid. Counts need consent: true, as for placements.list.

Errors and checks

An expired or revoked link stops working; make a new one with share(). All codes are in check codes and errors.

Swapping drivers

share has one real driver, getqr.id, by design (ADR-0009), whichever files driver stores the file. local runs the same contract in process for development and tests: links look like <origin>/_mainsdk/s/<id> and open with no network.

Testing

createTestApp() runs share on the local driver with a fake clock, so links expire with no real waiting.

The getqr.id contract itself is tested offline: 20 recorded calls are replayed through httpTransport and checked against the pinned openapi.yaml on every run, and mainsdk contract record --vendor getqr refreshes them (see contract record).

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

describe("share", () => {
  it("files-share AC5 expires a link after its window", async () => {
    const testApp = createTestApp({ main: "./main.yaml" });
    const link = await share({ url: "https://app.example.com/reports/r1" }, { expiresIn: "7d" });
    assert.ok(!link.url.includes("reports"));          // nothing of the target is in the URL
    testApp.clock.advance("8d");
    assert.equal((await share.get(link.id)).status, "expired");
  });
});

Security and privacy

• Links are private by default, expiring and read-only. A link never authorises a write.
• The URL holds no email, name or record id in clear. Titles and metadata with an email, a phone number or a secret are refused before any request.
• Open counts are first-party and returned only with consent.
• Tenants are kept apart: a share made in one tenant is not found from another (MAIN-TENANT-0005).

What Cloud adds

share is free in your app. The Fleet plan adds revoking shared files across apps from the Fleet console. See Free in-app and Cloud.

FAQ

Can I use my own short domain? Not yet; links are on getqr.id.

Can a share link let someone edit? No. Links grant read-only access, and access other than read fails with MAIN-SHARE-0003.

Why "Powered by getqr.id" on every share sheet? Every share in a MainSDK app goes through getqr.id, and the components show it so people know where the link lives.

Next

• File uploads: upload the files you share.
• App links: links that open the right screen in your app.
• Protected files: files that stay under policy after they are shared.