Browser SDK

const Foil = await import("https://cdn.usefoil.com/t.js");
const foil = await Foil.start({ publishableKey: "pk_live_..." });

// At action time (signup, login, checkout)
const { sessionId, sealedToken } = await foil.getSession();

​

Load and initialize

<script type="module">
  const foilPromise = import("https://cdn.usefoil.com/t.js")
    .then((Foil) =>
      Foil.start({ publishableKey: "pk_live_your_publishable_key" })
    );

  const foil = await foilPromise;

  // Optional: subscribe to errors
  foil.onError((error) => {
    console.error(error.code, error.message);
  });

  // Optional: surface fingerprinting errors before the action
  void foil.waitForFingerprint().catch(console.error);
</script>

​

API reference

​

Module exports

​

Foil.start(options)

interface FoilStartOptions {
  publishableKey: string;   // pk_live_* or pk_test_*
}

function start(options: FoilStartOptions): Promise<FoilClient>;

• publishableKey is required. Pass a pk_live_* or pk_test_* key. Secret keys (sk_*) are rejected.
• start() is idempotent for the same key - calling it again with the same publishableKey resolves to the same client without re-bootstrapping. Calling it with a different key rejects with config.already_initialized.
• On success, signal collection has started. You don’t need to await anything else before calling getSession() at action time - the SDK will flush whatever it has collected.
• Rejections are FoilErrors (see Error codes): config.validation_failed, config.already_initialized, runtime.bootstrap_failed, runtime.integrity_failed, runtime.start_failed, runtime.start_timeout, or a transport.* code when Foil can’t create a session.
• A rejection with retryable: true applies to that attempt only. It usually means the network failed or Foil was unreachable while the session was being created. Call start() again, for example when the user submits, and getSession() retries the session.

​

FoilClient

interface FoilClient {
  getSession(): Promise<SessionHandoff>;
  waitForFingerprint(): Promise<void>;
  onError(handler: (error: FoilErrorPayload) => void): () => void;
  destroy(): void;
}

interface SessionHandoff {
  sessionId: string;     // sid_* - stable across getSession() calls on the same client
  sealedToken: string;   // base64 - opaque, verify server-side
}

​

getSession()

• Resolves with { sessionId, sealedToken }. Every call produces a fresh sealedToken; the sessionId stays the same for the lifetime of the client.
• Safe to call multiple times. Calling it twice - e.g. on submit retry - is fine; just send the most recent handoff.
• Concurrent calls are coalesced: if you issue two getSession() calls before the first resolves, both receive the same handoff.
• Tokens aren’t single use. Verification is stateless: the server SDKs decrypt a token, but they don’t record it or check its age, so the same token verifies every time you submit it. To reject repeated submissions, record the decision.event_id of each token you accept (it’s unique to each token) or the session_id if you want one action per session. See What verification doesn’t check.
• You do not need to await waitForFingerprint() first. getSession() waits for fingerprinting to finish before it returns, and every handoff carries a visitor_fingerprint. If fingerprinting can’t finish, getSession() rejects instead of returning a handoff without one.
• Rejects with a FoilError: runtime.unavailable when called before start() resolved or after destroy(), runtime.session_failed (retryable: true) when the handoff request fails or takes longer than 15 seconds, or a transport.* or API error code when the Foil API rejects the request. See Error codes.

​

waitForFingerprint()

• Optional. getSession() waits for fingerprinting on its own, so you never need this call to get a visitor ID in the handoff. Its only use is to surface a fingerprinting error earlier than getSession() would.
• No identity data is returned to the browser; the fingerprint ID is only visible server-side in the verified sealed token.
• Typical fingerprint resolution completes within a few hundred milliseconds. Don’t block your form submission on it - kick it off after start() and use getSession() at action time regardless.
• Safe to call in parallel with getSession().
• Rejects with runtime.fingerprint_failed (retryable: true, fatal: false), including when fingerprinting doesn’t finish within 10 seconds. Foil doesn’t score a session without a fingerprint, so getSession() can’t succeed until fingerprinting does. Retrying after a transient failure can succeed.

​

onError(handler)

• Returns an unsubscribe function: const off = foil.onError(fn); /* later */ off();.
• If a fatal error has already occurred before you attach the handler, it is replayed on the next microtask so you don’t miss it.
• The handler receives the error as a FoilErrorPayload (the toJSON() shape of FoilError), which doesn’t include cause. Exceptions thrown from your handler are swallowed to preserve event-emitter behavior - don’t rely on them propagating.
• onError reports the errors that stop the runtime, which are failures during load and start(). Failures from getSession() and waitForFingerprint() reject those promises and aren’t sent to onError.
• Use this for logging and observability. For control flow, await the promise from start() / getSession() / waitForFingerprint() and catch rejections.

​

destroy()

• Terminal. After destroy() the client cannot be restarted - discard the reference. Any subsequent getSession() / waitForFingerprint() calls reject with runtime.unavailable.
• Useful for SPAs that navigate away from a Foil-protected surface, or for tests that need to tear down between cases.
• Synchronous and best-effort - in-flight network requests may still complete in the background.

​

Getting a session handoff

async function submitSignup(formData) {
  const { sessionId, sealedToken } = await foil.getSession();

  await fetch("/api/signup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ...formData,
      foil: { sessionId, sealedToken },
    }),
  });
}

{
  "sessionId": "sid_7m2k9x4v8q1n5t3w6r0p2c4y8h",
  "sealedToken": "AQAA..."
}

​

Error handling

{
  "code": "config.validation_failed",
  "message": "Foil start options are invalid.",
  "retryable": false,
  "fatal": true,
  "operation": "start",
  "details": {
    "fieldErrors": [{ "field": "publishableKey", "issue": "required" }]
  }
}

​

Error codes

​

Fallback policy

async function getFoilHandoff() {
  try {
    return await foil.getSession();
  } catch (err) {
    if (err.code === 'transport.upgrade_required') {
      // Bundle is stale; reload the page so a fresh t.js loads.
      window.location.reload();
      return null;
    }
    if (err.retryable) {
      try {
        return await foil.getSession();
      } catch {
        // fall through to skip
      }
    }
    // Report to your error tracker and continue without a handoff.
    reportError(err);
    return null;
  }
}

// On the server, a missing handoff means you have no Foil signal for
// this request - fall open or fall closed based on the sensitivity of
// the action. See Going to production for guidance.

​

Best practices

• Start early - initialize on page load, not at action time
• Call getSession() late - right before the sensitive action for the freshest signal data
• Handle errors gracefully - if the SDK fails, your app should still work (degrade to a fallback policy)
• Don’t expose verdicts client-side - the browser API intentionally doesn’t return them

​

What’s next

• Server verification - verify the handoff on your backend
• Browser compatibility - supported browsers and known differences
• Quickstart - end-to-end integration in 5 minutes