Node.js SDK (private preview)

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 network errors and 429 responses
  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 by default, workflow-configurable
// 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",
  risk_tier: "review",
});

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 records
const { data: deliveries } = await stile.webhookEndpoints.listDeliveries("we_abc123", {
  status: "failed",
});

// Inspect and retry one failed attempt
const delivery = await stile.webhookEndpoints.retrieveDelivery(
  "we_abc123",
  "cm5x7k9h20000qwerty123456",
);
await stile.webhookEndpoints.retryDelivery("we_abc123", delivery.id);

// Rotate a compromised secret (the new secret is returned once)
const endpoint = await stile.webhookEndpoints.rotateSecret("we_abc123");
console.log(endpoint.secret);

// Send a synthetic event while testing your handler
await stile.webhookEndpoints.sendTest("we_abc123", {
  event_type: "verification_session.verified",
});

// 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 assessment = await stile.risk.score({
  ip: "203.0.113.10",
  email: "user@example.com",
  claimed_country: "US-CA",
});

if (assessment.recommendation === "block") {
  // Stop or route the transaction to manual review.
}

const sameAssessment = await stile.risk.retrieve(assessment.id);

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

if (result.verified) {
  // This authenticated user already has a qualifying credential.
  console.log(result.verified_person_id, result.credentials);
} else {
  // Create a session and load the SDK
}

export async function POST(req: Request) {
  let event;
  try {
    event = await stile.webhooks.fromRequest(req, process.env.WEBHOOK_SECRET!);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  if (event.type === "verification_session.verified") {
    console.log("Session verified:", event.data.object.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 exhausted maxRetries; wait before trying again
  } else if (err instanceof StileError) {
    console.error(err.statusCode, err.type, err.code, err.message);
    // Include err.requestId when contacting support
  }
}