Node.js SDK

import Stile from "@stile/node";

const stile = new Stile(process.env.STILE_API_KEY!);

const stile = new Stile(process.env.STILE_API_KEY!, {
  baseUrl: "https://api.stile.id",
  maxRetries: 2, // default, retries on 5xx, network errors, and 429s
  timeout: 30_000, // default, 30 seconds
});

const session = await stile.verificationSessions.create({
  type: "age",
  workflow_id: "wf_YOUR_WORKFLOW_ID",
  return_url: "https://yourapp.com/verify/done",
  cancel_url: "https://yourapp.com/verify/cancel",
  client_reference_id: "user_123",
  // Optional: pass delivery address jurisdiction for VPN mismatch detection
  delivery_jurisdiction: "US-OR",
});

// session.id                  — e.g. "vks_abc123"
// session.client_secret       — pass to the frontend widget
// session.methods             — resolved from the workflow
// session.age_tier            — e.g. "min_age_21", resolved from workflow + jurisdiction
// session.expires_at          — Unix timestamp (24h from now)
// session.status              — "created"
// session.ip_jurisdiction     — "US-CA" (detected from IP, if delivery_jurisdiction was set)
// session.jurisdiction_mismatch — true if delivery ≠ IP jurisdiction

const session = await stile.verificationSessions.create(
  { type: "age", workflow_id: "wf_YOUR_WORKFLOW_ID" },
  { idempotencyKey: "order_12345" },
);

const session = await stile.verificationSessions.retrieve("vks_abc123");

// Include the full verification results array:
const expanded = await stile.verificationSessions.retrieve("vks_abc123", {
  expand: ["results"],
});

const session = await stile.verificationSessions.cancel("vks_abc123");
// session.status === "cancelled"

const { data, has_more } = await stile.verificationSessions.list({
  limit: 20,
  starting_after: "vks_xyz",
  status: "verified",
});

const endpoint = await stile.webhookEndpoints.create({
  url: "https://yourapp.com/api/webhooks",
  enabled_events: ["verification_session.verified", "verification_session.failed"],
  description: "Production webhook",
});
// endpoint.secret — save this to verify signatures

// Retrieve
const ep = await stile.webhookEndpoints.retrieve("we_abc123");

// Update
await stile.webhookEndpoints.update("we_abc123", {
  enabled_events: ["*"],
  status: "enabled",
});

// Delete
await stile.webhookEndpoints.del("we_abc123");

// List
const { data } = await stile.webhookEndpoints.list();

// List delivery attempts
const { data: deliveries } = await stile.webhookEndpoints.listDeliveries("we_abc123");

// Retrieve a single event
const event = await stile.events.retrieve("evt_abc123");

// List events, optionally filtered by type
const { data } = await stile.events.list({
  limit: 20,
  type: "verification_session.verified",
});

// Check what's allowed in the user's jurisdiction
const compliance = await stile.compliance.check({
  use_cases: ["alcohol_delivery", "tobacco_nicotine"],
  jurisdiction: "US-CA",
});

if (compliance.most_restrictive.any_prohibited) {
  // Some products can't be sold here
  console.log("Prohibited:", compliance.most_restrictive.prohibited_use_cases);
  // Remove prohibited items from the cart or show an error
}

// Create a session — the workflow carries the use case, and the API
// resolves the age tier internally
const session = await stile.verificationSessions.create({
  type: "age",
  workflow_id: "wf_YOUR_WORKFLOW_ID",
  client_reference_id: "order_456",
});

const result = await stile.verifiedPersons.lookup({
  email: "user@example.com",
  methods: ["document_capture"],
  min_strength: "document_capture",
  max_age: "30", // days
});

if (result.verified) {
  // User already verified — grant access, skip SDK
  console.log(result.verified_person_id, result.credentials);
} else {
  // Create a session and load the SDK
}

export async function POST(req: Request) {
  const event = await stile.webhooks.fromRequest(req, process.env.WEBHOOK_SECRET!);

  if (event.type === "verification_session.verified") {
    console.log("Session verified:", event.data.id);
  }

  return Response.json({ received: true });
}

const event = stile.webhooks.constructEvent(
  rawBody, // string or Buffer
  signatureHeader, // stile-signature header value
  process.env.WEBHOOK_SECRET!,
);

import { StileError, StileAuthenticationError, StileRateLimitError } from "@stile/node";

try {
  await stile.verificationSessions.create({ type: "identity", workflow_id: "wf_..." });
} catch (err) {
  if (err instanceof StileAuthenticationError) {
    // 401 — invalid or expired API key
  } else if (err instanceof StileRateLimitError) {
    // 429 — the SDK already retried (maxRetries); back off before trying again
  } else if (err instanceof StileError) {
    console.error(err.statusCode, err.type, err.code, err.message);
    // Include err.requestId when contacting support
  }
}