LLM-Optimized Integration Guide

Host Application (yours)
  |
  |-- Backend (Node.js / Python / any)
  |     |
  |     |-- POST /api/embed/onboard      --> One-time: create tenant + user + embedToken (uses appId + appSecret)
  |     |-- POST /api/embed/sessions      --> Per-page-load: create session (uses appId + appSecret + embedToken)
  |     |
  |     |-- After session is created, use X-Session-Id for everything:
  |     |     |-- POST /api/embed/users   --> Add new users to your tenant
  |     |     |-- GET  /api/embed/users   --> List users in your tenant
  |     |     |-- POST /api/embed/extract --> Upload & extract documents
  |     |
  |     |-- Stores: appId, appSecret, embedToken (NEVER in frontend)
  |     |
  |-- Frontend (React / Vue / any)
        |
        |-- <iframe src="/embed?sessionId=ess_xxx" />   (only sessionId exposed)
        |-- window.addEventListener('message', ...)      (listen for events)

# 3PM Extractor Configuration
EXTRACTOR_BASE_URL=https://extractor.decoded.digital
EXTRACTOR_APP_ID=673abc123def456789012345
EXTRACTOR_APP_SECRET=ask_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EXTRACTOR_EMBED_TOKEN=ext_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# For frontend (safe to expose)
NEXT_PUBLIC_EXTRACTOR_URL=https://extractor.decoded.digital

# Session-based auth (for all calls after onboarding):
X-Session-Id: ess_xxx...
# One header. Session contains all context (app, tenant, user).
# Works for: user creation, user listing, extractions, documents, etc.

# App-Secret auth (only for initial onboarding):
X-App-Id: YOUR_APP_ID
X-App-Secret: ask_xxx...
# Used only for POST /api/embed/onboard and POST /api/embed/sessions.

import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  // 1. Get authenticated user email from your auth system
  const userEmail = 'user@example.com'; // Replace with your auth

  // 2. Create session with Extractor
  const response = await fetch(
    `${process.env.EXTRACTOR_BASE_URL}/api/embed/sessions`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        appId: process.env.EXTRACTOR_APP_ID,
        appSecret: process.env.EXTRACTOR_APP_SECRET,
        embedToken: process.env.EXTRACTOR_EMBED_TOKEN,
        userEmail,
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return NextResponse.json({ error: 'Failed' }, { status: 500 });
  }

  // 3. Return only sessionId to frontend
  return NextResponse.json({ sessionId: data.data.sessionId });
}

'use client';
import { useEffect, useState } from 'react';

export function ExtractorEmbed({ page = 'upload', height = 600 }) {
  const [sessionId, setSessionId] = useState(null);

  useEffect(() => {
    fetch('/api/extractor/session', { method: 'POST' })
      .then(res => res.json())
      .then(data => setSessionId(data.sessionId))
      .catch(console.error);
  }, []);

  if (!sessionId) return <div>Loading...</div>;

  const pagePath = page === 'upload' ? '' : `/${page}`;
  const src = `${process.env.NEXT_PUBLIC_EXTRACTOR_URL}/embed${pagePath}?sessionId=${sessionId}`;

  return (
    <iframe
      src={src}
      width="100%"
      height={height}
      frameBorder="0"
      allow="clipboard-write"
    />
  );
}

uploaded → analyzing → analyzed → extracting → completed
              ↓                       ↓
        analysis failed        extraction failed
              ↓                       ↓
            failed                  failed

Statuses: uploaded, analyzing, analyzed, extracting, completed,
          analysis failed, extraction failed, failed