Know when a visitor arrives—and react in real time.

CORE CONCEPTS

The four objects in an integration.

Account and guest workspaces

You can try one redirect as a guest in the web workspace. Guest ownership is tied to a signed, HttpOnly browser cookie and does not provide API or client-library access. Sign in to manage multiple redirects and create revocable API tokens for integrations.

QUICK START

Create a connected redirect from your backend.

1. Create an API token

   Open the workspace, sign in, and create a token under Developer access. Copy it immediately; the raw token is shown only once.

2. Store the token on your server

   SCANSOCKET_API_TOKEN=ss_live_...

   Never include this value in browser code or a public repository.

3. Install the client

   npm install @scansocket/client

4. Create a redirect

   import { ScanSocketClient } from "@scansocket/client";
   
   const client = new ScanSocketClient(
     "https://scansocket-9eq5sywt5-sandro-padins-projects.vercel.app",
     process.env.SCANSOCKET_API_TOKEN!,
   );
   
   const redirect = await client.createRedirect({
     url: "https://your-app.example/welcome",
     // expiresAt: "2027-01-01T00:00:00.000Z",
     // visitorMessaging: "authenticated" | "public", // Default: "disabled"
   });
   
   console.log(redirect.shortUrl); // Put this URL in your own QR code or link
   console.log(redirect.qrCode);   // Or render this PNG data URL directly

5. Listen and react

   const unsubscribe = client.subscribe(
     redirect,
     (event) => {
       switch (event.type) {
         case "connected":
           console.log("Visitor connected", event.data.connectionId);
           void client.sendMessage(redirect, event.data.connectionId, { status: "ready" });
           break;
         case "message":
           console.log("Visitor message", event.data.connectionId, event.data.data);
           break;
         case "disconnected":
           console.log("Visitor disconnected", event.data.connectionId);
       }
     },
     (error) => console.error("Event stream stopped", error),
   );
   
   // Call this when your process, request, or component ends.
   unsubscribe();

DESTINATION HANDOFF

Read the connection ID from the destination URL.

Each successful visit adds scanSocketConnectionId to the destination URL. The owner receives the same value as connectionId in the connected event.

Existing query parameters and the URL fragment are preserved.

Redirect semantics

The 307 status preserves the request method, although public short URLs currently handle GET. Missing redirects return 404. Expired redirects return 410 and do not forward the visitor.

CLIENT REFERENCE

A small API with explicit stream lifecycle control.

Redirect result

Async iteration and backpressure

const controller = new AbortController();

for await (const event of client.events(redirect, {
  signal: controller.signal,
  cursor: 0,
})) {
  await processEvent(event); // Events are yielded in order
}

controller.abort();

HTTP API

Use bearer authentication from trusted code.

Send Authorization: Bearer $SCANSOCKET_API_TOKEN to every account API. JSON responses use Content-Type: application/json.

curl https://scansocket-9eq5sywt5-sandro-padins-projects.vercel.app/api/redirects \
  --request POST \
  --header "Authorization: Bearer $SCANSOCKET_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://your-app.example/welcome"}'

curl https://scansocket-9eq5sywt5-sandro-padins-projects.vercel.app/api/redirects \
  --header "Authorization: Bearer $SCANSOCKET_API_TOKEN"

Common errors

EVENT STREAMS

Resume reliably from the last processed event.

The owner stream emits events in ascending numeric ID order. Each current visit produces a connected event:

{
  "id": 42,
  "redirectId": "d0b18e0f-...",
  "type": "connected",
  "occurredAt": "2026-07-11T18:24:03.000Z",
  "data": {
    "connectionId": "93a70b4b-...",
    "userAgent": "Mozilla/5.0 ...",
    "referer": "https://example.com/"
  }
}

Visitor metadata is best-effort. ip, userAgent, and referer may be absent; do not make core behavior depend on them. Treat connectionId as an opaque string.

Server-Sent Events

The default response uses text/event-stream. Resume with the Last-Event-ID header or ?cursor=<id>. Event names match the event type; each data field contains the complete JSON event.

JSON Lines

The client requests application/x-ndjson. Each non-empty line is one complete event. Pass ?cursor=<id> to receive events after that ID.

Owner event types

connected carries { connectionId, ip?, userAgent?, referer? } for the initial visit and { connectionId } after a disconnected visitor returns. message carries { connectionId, data }. disconnected carries { connectionId }. All share id, redirectId, and occurredAt.

VISITOR MESSAGES

Send data to one specific visit.

Visitor-to-owner messaging is off by default and is configured when the redirect is created. This setting does not affect owner-to-visitor messages or visitor SSE presence.

Public browser messaging

import { ScanSocketVisitorClient } from "@scansocket/client";

const connectionId = new URL(window.location.href).searchParams.get(
  "scanSocketConnectionId",
);

if (!connectionId) throw new Error("Missing ScanSocket connection ID");

const source = new EventSource(
  `https://scansocket-9eq5sywt5-sandro-padins-projects.vercel.app/api/connections/${connectionId}/events`,
);

source.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  console.log(message.data);
});

// Sending without a token requires visitorMessaging: "public".
const visitor = new ScanSocketVisitorClient("https://scansocket-9eq5sywt5-sandro-padins-projects.vercel.app");
await visitor.sendMessage(connectionId, { answer: "B" });

// Later, close the stream when the destination no longer needs it:
// source.close();

Authenticated server forwarding

// Trusted application backend only. First authenticate and validate
// the visitor request using your application's normal session.
await client.sendVisitorMessage(connectionId, { answer: "B" });

Never embed or forward the ScanSocket owner token to the visitor. Authenticate and validate the visitor request in your own backend before calling sendVisitorMessage.

Each SSE message contains id, connectionId, sentAt, and your original data value. Resume with Last-Event-ID or ?cursor=<id>.

Presence and reconnects

The initial short-link visit creates the first connected event. Opening the visitor SSE stream marks that connection active. When every stream for the connection disappears, ScanSocket waits 10 seconds before appending disconnected. Reconnecting within the grace period preserves the session; returning later appends another connected.

Duplicate tabs and multiple EventSource instances create independent leases, so closing one does not disconnect the connection while another remains. Normal closes, network loss, and the server's planned stream rotation use the same grace behavior. Expiration prevents new short-link visits but does not terminate an existing connection. Deleting a redirect cascades its connections and no final disconnected event is retained.

SECURITY & LIMITS

Design the integration around clear trust boundaries.

• Keep API tokens in server-side environment variables or a secrets manager. The client supports browsers technically, but privileged methods should run only in trusted code.
• Visitor messaging defaults to disabled. Prefer authenticated for messages affecting identity, scores, purchases, permissions, or other trusted state. Use public only for deliberately anonymous, low-risk input.
• Create separate tokens for development, staging, and production so you can revoke each independently.
• A token can create, list, and delete redirects and consume events for its account. Raw token values are not stored and are shown only once.
• Revoking a token immediately blocks authenticated API and owner-stream access through that token. It does not disable existing public short URLs.
• Delete a redirect to stop future visits. Use expiresAt when it should stop automatically at a known time.
• Owner and visitor messages are limited to 16 KB of UTF-8 serialized JSON. Visitor requests are limited to 20 KB and 30 messages per connection per 10-second window.
• Connection and event streams may reconnect. Resume from the last processed cursor and make handlers duplicate-safe.