nyne-enrichment

使用 Nyne Enrichment API 通过电子邮件、电话、LinkedIn URL 或姓名丰富任何人。 返回联系信息、社交资料、工作历史、教育背景和可选的社交媒体帖子。 支持精简模式（3 学分）、新闻源附加组件和人工智能增强型深度搜索。与轮询异步。

## 概述（中文）

使用 Nyne Enrichment API 通过电子邮件、电话、LinkedIn URL 或姓名丰富任何人。
返回联系信息、社交资料、工作历史、教育背景和可选的社交媒体帖子。
支持精简模式（3 学分）、新闻源附加组件和人工智能增强型深度搜索。与轮询异步。

## 原文

# Nyne Enrichment Skill

Enrich any person by email, phone, LinkedIn URL, or name. Returns contact info, social profiles, work history, education, and optional social media posts.

**Important:** This API is async. You POST to submit, get a `request_id`, then poll GET until complete.

## Agent Instructions

When presenting results to the user, show **all available data**. Walk through each section:

1. **Identity** — displayname, bio, location, gender
2. **Contact** — emails (work + personal + alt), phones with type
3. **Social Profiles** — LinkedIn, Twitter, GitHub, Instagram with follower counts
4. **Work History** — all organizations with title, dates, current status
5. **Education** — schools with degree, field, dates
6. **Newsfeed** (if requested) — recent posts with engagement metrics

If a field is missing from the response, it means no data was found — skip it silently.

For lite mode responses, note that only 5 fields are returned (displayname, firstname, lastname, first organization, LinkedIn URL).

## Setup

**Required environment variables:**
- `NYNE_API_KEY` — your Nyne API key
- `NYNE_API_SECRET` — your Nyne API secret

Get credentials at [https://api.nyne.ai](https://api.nyne.ai).

```bash
export NYNE_API_KEY="your-api-key"
export NYNE_API_SECRET="your-api-secret"
```

Verify they're set:
```bash
echo "Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}..."
```

## Important: JSON Handling

The API response can contain control characters in JSON string values that break `jq`. All examples use a `nyne_parse` helper that cleans and re-encodes JSON via `python3`. Define it once per session:

```bash
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
```

## Quick Start

Submit an enrichment request by email and poll until complete:

```bash
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}

# Submit enrichment request
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
echo "Request submitted: $REQUEST_ID"

# Poll until complete (checks every 3s, times out after 6 min)
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 360 ]; do
  curl -s "https://api.nyne.ai/person/enrichment?request_id=$REQUEST_ID" \
    -H "X-API-Key: $NYNE_API_KEY" \
    -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_enrich.json
  STATUS=$(jq -r '.data.status' /tmp/nyne_enrich.json)
  echo "Status: $STATUS ($SECONDS_WAITED seconds elapsed)"
  if [ "$STATUS" = "completed" ]; then
    jq '.data.result' /tmp/nyne_enrich.json
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Enrichment failed."
    jq . /tmp/nyne_enrich.json
    break
  fi
  sleep 3
  SECONDS_WAITED=$((SECONDS_WAITED + 3))
done

if [ $SECONDS_WAITED -ge 360 ]; then
  echo "Timed out after 6 minutes. Resume polling with request_id: $REQUEST_ID"
fi
```

## Submit Enrichment (POST)

**Endpoint:** `POST https://api.nyne.ai/person/enrichment`

**Headers:**
```
Content-Type: application/json
X-API-Key: $NYNE_API_KEY
X-API-Secret: $NYNE_API_SECRET
```

### Input Parameters

At least one identifier is required.

| Parameter | Type | Description |
|-----------|------|-------------|
| `email` | string | Email address (work email preferred) |
| `phone` | string | Phone number (e.g., "+14155551234") |
| `social_media_url` | string | LinkedIn, Twitter, or GitHub URL |
| `name` | string | Full name (use with `company` or `city` to disambiguate) |
| `company` | string | Company name (helps disambiguate name lookups) |
| `city` | string | City (accepts abbreviations: SF, NYC, LA) |

**Input priority ranking:** LinkedIn URL (best) > Email (work > personal) > Phone (lowest match rate). LinkedIn + email together yields best results.

### Feature Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ai_enhanced_search` | boolean | false | AI-powered deep search for additional social profiles. Longer processing time. |
| `lite_enrich` | boolean | false | Minimal enrichment: only 5 fields, 3 credits instead of 6 |
| `newsfeed` | array | omit | Social posts to fetch: `["linkedin", "twitter", "instagram", "github", "facebook"]` or `["all"]`. Cannot mix `"all"` with specific sources. +6 credits when data found. |
| `strict_email_check` | boolean | false | Strict email validation (may return no results) |
| `callback_url` | string | omit | Webhook URL for async delivery |

### Examples

**By email:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
echo "Request ID: $REQUEST_ID"
```

**By LinkedIn URL:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"social_media_url": "https://linkedin.com/in/johndoe"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**By name + company:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"name": "Jane Smith", "company": "Acme Corp", "city": "SF"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**With newsfeed:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "newsfeed": ["linkedin", "twitter"]}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**Lite mode (3 credits):**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "lite_enrich": true}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**With AI-enhanced search:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "ai_enhanced_search": true}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**Submit response:**
```json
{
  "success": true,
  "data": {
    "request_id": "abc123-...",
    "status": "queued",
    "message": "Enrichment request queued. Use GET /person/enrichment?request_id=... to check status."
  }
}
```

## Poll for Results (GET)

**Endpoint:** `GET https://api.nyne.ai/person/enrichment?request_id={id}`

**Headers:** Same `X-API-Key` and `X-API-Secret` as above.

### Check status once
```bash
curl -s "https://api.nyne.ai/person/enrichment?request_id=$REQUEST_ID" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_enrich.json

jq '{status: .data.status, completed: .data.completed}' /tmp/nyne_enrich.json
```

### Full polling loop

```bash
SECONDS_WAITED=0
TIMEO