API Reference

import naralin

client = naralin.Client()  "color:#565f89"># reads NARALIN_API_KEY

try:
    result = client.entity.lookup("Acme Corp", jurisdiction="gb")
    print(f"Risk: {result.risk_level} ({result.risk_score}/100)")

except naralin.AuthenticationError as e:
    print(f"Auth failed: {e.message}")

except naralin.QuotaExceededError as e:
    "color:#565f89"># Monthly limit exhausted — do not retry
    print(f"Quota: {e.used}/{e.limit} — resets {e.reset_at}")

except naralin.RateLimitError as e:
    "color:#565f89"># SDK retries automatically; only raised after max retries
    import time; time.sleep(e.retry_after)

except naralin.NaralinError as e:
    print(f"API error [{e.error_code}]: {e.message}")

import Naralin, {
  AuthenticationError, QuotaExceededError, RateLimitError, NaralinError,
} from 'naralin';

const client = new Naralin();

try {
  const result = await client.entity.lookup({ name: 'Acme Corp', jurisdiction: 'gb' });
  console.log(`Risk: ${result.risk_level} (${result.risk_score}/100)`);

} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Auth failed:', err.message);
  } else if (err instanceof QuotaExceededError) {
    console.error(`Quota: ${err.used}/${err.limit} — resets ${err.resetAt}`);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${err.retryAfter}s`);
  } else if (err instanceof NaralinError) {
    console.error(`API error [${err.code}]: ${err.message}`);
  }
}

from dataclasses import dataclass
from typing import Optional
import naralin

client = naralin.Client()

@dataclass
class OnboardingDecision:
    approved: bool
    reason: str
    entity_id: Optional[str]
    risk_level: str
    flags: list[str]

def screen_for_onboarding(name: str, jurisdiction: str) -> OnboardingDecision:
    try:
        result = client.entity.lookup(name, jurisdiction=jurisdiction)
    except naralin.QuotaExceededError as e:
        return OnboardingDecision(
            approved=False, reason=f"Screening unavailable (resets {e.reset_at})",
            entity_id=None, risk_level="UNKNOWN", flags=["screening_unavailable"],
        )

    if not result.found:
        return OnboardingDecision(
            approved=False, reason="Entity not found — manual review required",
            entity_id=None, risk_level="UNKNOWN", flags=["not_found"],
        )

    if result.has_active_sanctions:
        return OnboardingDecision(
            approved=False,
            reason=f"Active sanctions: {', '.join(result.sanctioned_lists)}",
            entity_id=result.entity_id, risk_level=result.risk_level,
            flags=result.risk_factors,
        )

    if result.has_active_debarment:
        return OnboardingDecision(
            approved=False, reason="Active debarment from procurement programs",
            entity_id=result.entity_id, risk_level=result.risk_level,
            flags=result.risk_factors,
        )

    if result.is_high_risk:
        return OnboardingDecision(
            approved=False, reason=f"Risk level {result.risk_level} exceeds threshold",
            entity_id=result.entity_id, risk_level=result.risk_level,
            flags=result.risk_factors,
        )

    if result.requires_review:
        return OnboardingDecision(
            approved=False, reason="Enhanced due diligence required",
            entity_id=result.entity_id, risk_level=result.risk_level,
            flags=result.risk_factors,
        )

    return OnboardingDecision(
        approved=True, reason="Passed automated screening",
        entity_id=result.entity_id, risk_level=result.risk_level, flags=[],
    )

from framework import App, Depends, HTTPException
from pydantic import BaseModel
import naralin

app = App()
naralin_client = naralin.Client()

class CounterpartyRequest(BaseModel):
    company_name: str
    jurisdiction: str | None = None

async def require_clean_entity(req: CounterpartyRequest):
    "color:#9ece6a">"""Dependency: screen the counterparty and reject high-risk entities."""
    try:
        result = naralin_client.entity.lookup(
            req.company_name, jurisdiction=req.jurisdiction
        )
    except naralin.QuotaExceededError:
        raise HTTPException(503, detail="Screening temporarily unavailable")

    if not result.found:
        raise HTTPException(422, detail="Entity could not be verified")

    if result.has_active_sanctions or result.is_high_risk:
        raise HTTPException(403, detail=f"Counterparty rejected: {result.risk_level} risk")

    return result

@app.post("/onboard")
async def onboard_customer(
    body: CounterpartyRequest,
    entity = Depends(require_clean_entity),
):
    return {"status": "approved", "entity_id": entity.entity_id, "risk_level": entity.risk_level}

'use server';
import Naralin, { QuotaExceededError, NaralinError } from 'naralin';

const client = new Naralin(); "color:#565f89">// reads process.env.NARALIN_API_KEY

export async function screenEntity(formData: FormData) {
  const name = formData.get('company_name') as string;
  const jurisdiction = formData.get('jurisdiction') as string | undefined;

  try {
    const result = await client.entity.lookup({ name, jurisdiction });

    if (!result.found) {
      return { status: 'not_found' as const };
    }
    if (result.isHighRisk) {
      return {
        status: 'rejected' as const,
        riskLevel: result.risk_level,
        factors: result.risk_factors,
        sanctions: result.sanctionedLists,
      };
    }
    if (result.requiresReview) {
      return { status: 'review' as const, riskLevel: result.risk_level, entityId: result.entity_id };
    }
    return { status: 'approved' as const, entityId: result.entity_id, riskLevel: result.risk_level };

  } catch (err) {
    if (err instanceof QuotaExceededError) {
      return { status: 'error' as const, message: `Screening unavailable — resets ${err.resetAt}` };
    }
    if (err instanceof NaralinError) {
      return { status: 'error' as const, message: err.message };
    }
    throw err;
  }
}