@fiberai/sdk 0.0.13 → 0.0.15

package/README.md

@@ -5,6 +5,21 @@ Official TypeScript/JavaScript SDK for the [Fiber AI](https://fiber.ai) API - Re
 [![npm version](https://img.shields.io/npm/v/@fiberai/sdk.svg)](https://www.npmjs.com/package/@fiberai/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## For AI agents (Cursor / Claude / Codex / ChatGPT / Copilot)
+
+Do NOT guess operation names — read the canonical agent-facing docs first:
+
+- **Routing index + critical rules:** https://api.fiber.ai/llms.txt
+- **Per-operation markdown:** `https://api.fiber.ai/ai-docs/<operationId>.md`
+  (e.g. [`companySearch`](https://api.fiber.ai/ai-docs/companySearch.md),
+  [`syncQuickContactReveal`](https://api.fiber.ai/ai-docs/syncQuickContactReveal.md),
+  [`triggerExhaustiveContactEnrichment`](https://api.fiber.ai/ai-docs/triggerExhaustiveContactEnrichment.md))
+- **Operation index:** https://api.fiber.ai/ai-docs/index.md
+- **Full corpus (single file):** https://api.fiber.ai/llms-full.txt
+- **OpenAPI spec:** `https://api.fiber.ai/openapi.json`
+  (send `Accept: text/markdown` for the agent-friendly variant)
+- **MCP server:** `https://mcp.fiber.ai/mcp/v2` (also see [fiber-ai/mcp](https://github.com/fiber-ai/mcp))
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -14,13 +29,13 @@ Official TypeScript/JavaScript SDK for the [Fiber AI](https://fiber.ai) API - Re
   - [Company & People Search](#company--people-search)
   - [Contact Enrichment](#contact-enrichment)
   - [LinkedIn Live Enrichment](#linkedin-live-enrichment)
-  - [Saved Searches (Audiences)](#saved-searches-audiences)
   - [Exclusion Lists](#exclusion-lists)
   - [Google Maps Search](#google-maps-search)
   - [AI-Powered Research](#ai-powered-research)
 - [Advanced Usage](#advanced-usage)
 - [Error Handling](#error-handling)
 - [TypeScript Support](#typescript-support)
+  - [Runtime Validation with Zod](#runtime-validation-with-zod)
 - [Rate Limits & Credits](#rate-limits--credits)
 - [Support](#support)
 
@@ -39,48 +54,58 @@ pnpm add @fiberai/sdk
 ## Quick Start
 
 ```typescript
-import { peopleSearch, companySearch, getOrgCredits } from '@fiberai/sdk';
+import { peopleSearch, companySearch, getOrgCredits } from "@fiberai/sdk";
 
 // Check your organization's credit balance
 const credits = await getOrgCredits({
-  query: { apiKey: 'your-api-key' }
+  query: { apiKey: "your-api-key" },
 });
 
-console.log(`Available credits: ${credits.data.output.available}`);
+console.log(`Available credits: ${credits.data?.output.available}`);
 
 // Search for companies
 const companies = await companySearch({
   body: {
-    apiKey: 'your-api-key',
+    apiKey: "your-api-key",
     searchParams: {
       industriesV2: {
-        anyOf: ['Software', 'Information Technology']
+        anyOf: ["Software", "Information Technology"],
       },
+      // Bucket-valued range. Allowed bounds: 0 | 1 | 10 | 50 | 200 | 500 | 1000 | 5000 | 10000 | null.
       employeeCountV2: {
-        lowerBoundExclusive: 100,
-        upperBoundInclusive: 1000
+        lowerBoundExclusive: 50,
+        upperBoundInclusive: 1000,
       },
       headquartersCountryCode: {
-        anyOf: ['USA']
-      }
+        anyOf: ["USA"],
+      },
     },
-    pageSize: 25
-  }
+    pageSize: 25,
+  },
 });
 
 // Search for people
 const people = await peopleSearch({
   body: {
-    apiKey: 'your-api-key',
+    apiKey: "your-api-key",
     searchParams: {
-      title: ['CEO', 'CTO', 'VP Engineering'],
-      location: {
-        cities: ['San Francisco, CA']
-      }
+      jobTitleV2: {
+        anyOf: [
+          { type: "term", term: "CEO" },
+          { type: "term", term: "CTO" },
+          { type: "static-groups", groups: ["c-suite"] },
+        ],
+      },
+      country3LetterCode: { anyOf: ["USA"] },
     },
-    pageSize: 25
-  }
+    pageSize: 25,
+  },
 });
+
+// Every successful response also carries a `chargeInfo` envelope alongside
+// `output`. Source of truth for cost — prefer this over the static table below.
+console.log(people.data?.chargeInfo);
+// e.g. { method: 'charged-now', creditsCharged: 25, lowCreditAlert: null }
 ```
 
 ## Authentication
@@ -97,13 +122,15 @@ All API requests require an API key. Get yours at [fiber.ai/app/api](https://fib
 await companySearch({
   body: {
     apiKey: process.env.FIBERAI_API_KEY,
-    searchParams: { /* ... */ }
-  }
+    searchParams: {
+      /* ... */
+    },
+  },
 });
 
 // GET request example
 await getOrgCredits({
-  query: { apiKey: process.env.FIBERAI_API_KEY }
+  query: { apiKey: process.env.FIBERAI_API_KEY },
 });
 ```
 
@@ -123,7 +150,7 @@ FIBERAI_API_KEY=your_api_key_here
 Search for companies using 40+ filters including industry, location, revenue, funding, and more.
 
 ```typescript
-import { companySearch, companyCount } from '@fiberai/sdk';
+import { companySearch, companyCount } from "@fiberai/sdk";
 
 // Advanced company search
 const result = await companySearch({
@@ -132,46 +159,51 @@ const result = await companySearch({
     searchParams: {
       // Industry filters
       industriesV2: {
-        anyOf: ['Software', 'Cloud']
+        anyOf: ["Software", "Cloud"],
       },
-      
+
       // Size filters
       employeeCountV2: {
         lowerBoundExclusive: 50,
-        upperBoundInclusive: 500
+        upperBoundInclusive: 500,
       },
-      
+
       // Location filters
       headquartersCountryCode: {
-        anyOf: ['USA']
+        anyOf: ["USA"],
       },
-      
+
       // Funding filters
       totalFundingUSD: {
-        lowerBound: 1000000
+        lowerBound: 1000000,
       },
-      
+
       // Keywords filter
       keywords: {
-        containsAny: ['venture-backed-startup']
-      }
+        containsAny: ["venture-backed-startup"],
+      },
     },
     pageSize: 50,
-    cursor: null // For pagination
-  }
+    cursor: null, // For pagination
+  },
 });
 
-console.log(`Found ${result.data.output.data.items.length} companies`);
+console.log(`Found ${result.data?.output.data.length} companies`);
+console.log(
+  `Cursor for next page: ${result.data?.output.nextCursor ?? "none"}`,
+);
 
 // Get total count before searching
 const count = await companyCount({
   body: {
     apiKey: process.env.FIBERAI_API_KEY,
-    searchParams: { /* same filters */ }
-  }
+    searchParams: {
+      /* same filters */
+    },
+  },
 });
 
-console.log(`Total companies matching: ${count.data.output.count}`);
+console.log(`Total companies matching: ${count.data?.output.count}`);
 ```
 
 #### People Search
@@ -179,244 +211,283 @@ console.log(`Total companies matching: ${count.data.output.count}`);
 Find decision-makers and key contacts with precise targeting.
 
 ```typescript
-import { peopleSearch, peopleSearchCount } from '@fiberai/sdk';
+import { peopleSearch, peopleSearchCount } from "@fiberai/sdk";
 
 const people = await peopleSearch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
+    apiKey: process.env.FIBERAI_API_KEY!,
     searchParams: {
-      // Job title filters
-      title: ['CEO', 'Chief Executive Officer', 'Founder'],
-      
-      // Seniority and function
-      seniority: ['Executive'],
-      jobFunction: ['Entrepreneurship'],
-      
-      // Location filters
+      // Job title filter. Mix free-form `term` matches with curated
+      // `static-groups` ('founder' | 'c-suite' | 'board-member') and
+      // `dynamic-groups` ('vp' | 'director' | 'management' | 'entry-level' | ...).
+      jobTitleV2: {
+        anyOf: [
+          { type: "term", term: "CEO" },
+          { type: "term", term: "Chief Executive Officer" },
+          { type: "static-groups", groups: ["founder", "c-suite"] },
+        ],
+      },
+
+      // Country filter — ISO 3166-1 alpha-3 codes, not city names.
+      country3LetterCode: { anyOf: ["USA"] },
+
+      // Geographic radius filter (use this, not "cities"/"countries").
       location: {
-        cities: ['San Francisco, CA', 'New York, NY'],
-        countries: ['USA']
+        unionAll: [
+          {
+            strategy: "radial-distance",
+            center: { latitude: 37.7749, longitude: -122.4194 }, // San Francisco
+            radius: { unit: "miles", quantity: 50 },
+          },
+        ],
       },
-      
-      // Company filters (search within specific companies)
-      currentCompany: {
-        domains: ['example.com'],
-        linkedinUrls: ['https://linkedin.com/company/example']
+
+      // Curated tags. Allowed values include 'decision-maker', 'c-suite',
+      // 'experienced-executive', 'second-time-founder', 'phd', etc.
+      tags: { anyOf: ["decision-maker", "c-suite"] },
+
+      // Education filter — match by school identifier (LinkedIn id, slug,
+      // or domain), not by free-form school name.
+      education: {
+        anyOf: [
+          {
+            school: {
+              anyOf: [{ domain: "stanford.edu" }, { domain: "harvard.edu" }],
+            },
+          },
+        ],
       },
-      
-      // Tags and special filters
-      tags: ['decision-maker', 'c-suite'],
-      
-      // Education filters
-      schools: ['Stanford University', 'Harvard University']
+
+      getDetailedWorkExperience: true,
+      getDetailedEducation: true,
     },
+
+    // `currentCompanies` is a TOP-LEVEL body field, NOT inside searchParams.
+    // It expects concrete identifiers, not industry filters. To filter by
+    // industry/size/etc, use `syncCombinedSearch` and put company filters
+    // under `companyParams`.
+    currentCompanies: [
+      { domain: "example.com" },
+      { linkedinSlugOrURL: "https://linkedin.com/company/example" },
+    ],
+
     pageSize: 100,
-    getDetailedWorkExperience: true,
-    getDetailedEducation: true
-  }
+  },
 });
 
-// Access profile data
-people.data.output.data.items.forEach(profile => {
-  console.log(`${profile.name} - ${profile.headline}`);
+// Access profile data — `output.data` is a direct array, no `.items` wrapper.
+people.data?.output.data.forEach((profile) => {
+  console.log(`${profile.name} — ${profile.headline}`);
   console.log(`LinkedIn: ${profile.url}`);
-  if (profile.currentJob) {
-    console.log(`Current: ${profile.currentJob.title} at ${profile.currentJob.company_name}`);
+
+  // There is no `profile.currentJob` field. Current role lives in
+  // `experiences[]` filtered by `is_current`.
+  const currentRole = profile.experiences?.find((e) => e.is_current);
+  if (currentRole) {
+    console.log(`Current: ${currentRole.title} at ${currentRole.company_name}`);
   }
 });
+
+console.log(`Charged: ${people.data?.chargeInfo.method}`);
 ```
 
 #### Combined Search (Companies + People)
 
-Search for companies and their employees in one workflow.
+Return matching companies and their employees in a single synchronous call. Filter on the company side (`companyParams`) and the person side (`profileParams`) at the same time. For larger result sets you can also run `companySearch` and `peopleSearch` independently and paginate each.
 
 ```typescript
-import { combinedSearch, pollCombinedSearch } from '@fiberai/sdk';
+import { syncCombinedSearch } from "@fiberai/sdk";
 
-// Start async search
-const searchTask = await combinedSearch({
+const result = await syncCombinedSearch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    companySearchParams: {
+    apiKey: process.env.FIBERAI_API_KEY!,
+    companyParams: {
       industriesV2: {
-        anyOf: ['Software']
+        anyOf: ["Software"],
       },
       employeeCountV2: {
-        lowerBoundExclusive: 100
-      }
+        lowerBoundExclusive: 200,
+      },
     },
-    personSearchParams: {
-      title: ['VP of Sales', 'Sales Director'],
-      seniority: ['Director', 'Executive']
+    profileParams: {
+      jobTitleV2: {
+        anyOf: [
+          { type: "term", term: "VP of Sales" },
+          { type: "term", term: "Sales Director" },
+          { type: "static-groups", groups: ["c-suite"] },
+          { type: "dynamic-groups", groups: ["vp", "director"] },
+        ],
+      },
     },
-    maxCompanies: 100,
-    maxProspects: 500
-  }
+    companyItemLimit: 25,
+    profileItemLimit: 100,
+  },
 });
 
-const searchId = searchTask.data.output.searchId;
+result.data?.output.companies?.forEach((company) => {
+  console.log(company.preferred_name);
+});
 
-// Poll for companies
-let companyCursor = null;
-do {
-  const companies = await pollCombinedSearch({
-    body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      searchId,
-      entityType: 'company',
-      cursor: companyCursor,
-      pageSize: 25
-    }
-  });
-  
-  // Process companies
-  companies.data.output.data.items.forEach(company => {
-    console.log(company.preferred_name);
-  });
-  
-  companyCursor = companies.data.output.nextCursor;
-} while (companyCursor);
-
-// Poll for prospects
-let prospectCursor = null;
-do {
-  const prospects = await pollCombinedSearch({
-    body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      searchId,
-      entityType: 'profile',
-      cursor: prospectCursor,
-      pageSize: 100
-    }
-  });
-  
-  // Process profiles
-  prospects.data.output.data.items.forEach(profile => {
-    console.log(`${profile.name} - ${profile.headline}`);
-  });
-  
-  prospectCursor = prospects.data.output.nextCursor;
-} while (prospectCursor);
+result.data?.output.profiles?.forEach((profile) => {
+  console.log(`${profile.name} - ${profile.headline}`);
+});
 ```
 
+> See [`syncCombinedSearch`](https://api.fiber.ai/ai-docs/syncCombinedSearch.md) for the full parameter surface, or drive the two-step flow via `companySearch` + `peopleSearch` when you need cursor-based pagination.
+
 ### Contact Enrichment
 
-Get emails and phone numbers for LinkedIn profiles.
+Reveal emails and phone numbers for a known LinkedIn profile. Fiber exposes a **three-tier public contract** — pick the tier that matches your latency, coverage, and cost tradeoffs:
+
+| Tier       | Operation                                                                      | Shape                 | When to use                                                                                                   |
+| ---------- | ------------------------------------------------------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Default    | `syncQuickContactReveal`                                                       | Sync, one HTTP call   | Default single-profile reveal. Fast, good coverage.                                                           |
+| Premium    | `syncTurboContactEnrichment`                                                   | Sync, one HTTP call   | You need the absolute fastest response and want the widest first-pass waterfall. Premium cost.                |
+| Exhaustive | `triggerExhaustiveContactEnrichment` + `pollExhaustiveContactEnrichmentResult` | Async, trigger + poll | Highest coverage. Kick off a background waterfall that tries every available provider, then poll for results. |
 
-#### Single Contact Enrichment (Async)
+For lists of 10–2000 identifiers, use the batch endpoints instead (see [Batch Contact Reveal](#batch-contact-reveal)).
+
+#### Default — `syncQuickContactReveal`
 
 ```typescript
-import { triggerContactEnrichment, pollContactEnrichmentResult } from '@fiberai/sdk';
+import { syncQuickContactReveal } from "@fiberai/sdk";
 
-// Start enrichment
-const task = await triggerContactEnrichment({
+const result = await syncQuickContactReveal({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/in/example',
-    dataToFetch: {
-      workEmail: true,
-      personalEmail: true,
-      phoneNumber: true
+    apiKey: process.env.FIBERAI_API_KEY!,
+    linkedinUrl: "https://www.linkedin.com/in/example",
+    enrichmentType: {
+      getWorkEmails: true,
+      getPersonalEmails: true,
+      getPhoneNumbers: true,
     },
-    liveFetch: false // Set to true for real-time LinkedIn scraping (+1 credit)
-  }
+    // Emails are bounce-validated by default. Set validateEmails: false to skip.
+  },
 });
 
-// Poll for results
-let done = false;
-while (!done) {
-  await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
-  
-  const result = await pollContactEnrichmentResult({
-    body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      taskId: task.data.output.taskId
-    }
-  });
-  
-  done = result.data.output.done;
-  
-  if (done) {
-    const profile = result.data.output.profile;
-    console.log('Emails:', profile.emails);
-    console.log('Phone numbers:', profile.phoneNumbers);
-  }
-}
+console.log("Emails:", result.data?.output.profile?.emails);
+console.log("Phones:", result.data?.output.profile?.phoneNumbers);
 ```
 
-#### Single Contact Enrichment (Sync)
+#### Premium — `syncTurboContactEnrichment`
 
 ```typescript
-import { syncContactEnrichment } from '@fiberai/sdk';
+import { syncTurboContactEnrichment } from "@fiberai/sdk";
 
-// Synchronous enrichment (waits for completion)
-const result = await syncContactEnrichment({
+const result = await syncTurboContactEnrichment({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/in/example',
-    dataToFetch: {
-      workEmail: true,
-      personalEmail: false,
-      phoneNumber: false
-    }
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    linkedinUrl: "https://www.linkedin.com/in/example",
+    enrichmentType: {
+      getWorkEmails: true,
+      getPersonalEmails: true,
+      getPhoneNumbers: true,
+    },
+  },
 });
 
-console.log('Work emails:', result.data.output.profile.emails);
+console.log("Emails:", result.data?.output.profile?.emails);
 ```
 
-#### Batch Contact Enrichment
+#### Exhaustive (async waterfall) — `triggerExhaustiveContactEnrichment` + `pollExhaustiveContactEnrichmentResult`
 
-Enrich up to 10,000 contacts in one request.
+`triggerExhaustiveContactEnrichment` starts a background waterfall that returns the highest coverage at the cost of latency. It returns a `taskId` immediately; poll `pollExhaustiveContactEnrichmentResult` every 5–15s until `output.done === true`.
 
 ```typescript
-import { startBatchContactEnrichment, pollBatchContactEnrichment } from '@fiberai/sdk';
+import {
+  triggerExhaustiveContactEnrichment,
+  pollExhaustiveContactEnrichmentResult,
+} from "@fiberai/sdk";
 
-// Start batch enrichment
-const batch = await startBatchContactEnrichment({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    people: [
-      { linkedinUrl: { value: 'https://linkedin.com/in/person1' } },
-      { linkedinUrl: { value: 'https://linkedin.com/in/person2' } },
-      // ... up to 10,000 people
-    ],
-    dataToFetch: {
-      workEmail: true,
-      personalEmail: true,
-      phoneNumber: true
-    }
+const trigger: Awaited<ReturnType<typeof triggerExhaustiveContactEnrichment>> =
+  await triggerExhaustiveContactEnrichment({
+    body: {
+      apiKey: process.env.FIBERAI_API_KEY!,
+      linkedinUrl: "https://www.linkedin.com/in/example",
+      enrichmentType: {
+        getWorkEmails: true,
+        getPersonalEmails: true,
+        getPhoneNumbers: true,
+      },
+    },
+  });
+
+const taskId: string = trigger.data!.output.taskId;
+
+let done: boolean = false;
+while (!done) {
+  await new Promise<void>((resolve) => setTimeout(resolve, 5000));
+
+  const poll: Awaited<ReturnType<typeof pollExhaustiveContactEnrichmentResult>> =
+    await pollExhaustiveContactEnrichmentResult({
+      body: { apiKey: process.env.FIBERAI_API_KEY!, taskId },
+    });
+
+  done = poll.data?.output.done ?? false;
+  if (done) {
+    console.log("Emails:", poll.data?.output.profile.emails);
+    console.log("Phones:", poll.data?.output.profile.phoneNumbers);
+    console.log("Status:", poll.data?.output.profile.status);
   }
-});
+}
+```
+
+#### Batch Contact Reveal — `startBatchContactEnrichment` + `pollBatchContactEnrichment`
+
+For 10–2000 LinkedIn identifiers in one task. `startBatchContactEnrichment` charges credits up front and returns a `taskId`; `pollBatchContactEnrichment` returns paginated results with both per-task progress (`output.overallStats`) and `output.done` to gate the loop. For larger lists or repeatable workflows, upload a CSV-backed audience and enrich it through the audience workflow instead.
 
-// Poll for results with pagination
-let cursor = null;
-let allDone = false;
+```typescript
+import {
+  startBatchContactEnrichment,
+  pollBatchContactEnrichment,
+} from "@fiberai/sdk";
 
-while (!allDone) {
-  await new Promise(resolve => setTimeout(resolve, 5000));
-  
-  const results = await pollBatchContactEnrichment({
+const start: Awaited<ReturnType<typeof startBatchContactEnrichment>> =
+  await startBatchContactEnrichment({
     body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      taskId: batch.data.output.taskId,
-      cursor,
-      take: 100
-    }
-  });
-  
-  allDone = results.data.output.done;
-  cursor = results.data.output.nextCursor;
-  
-  // Process page results
-  results.data.output.pageResults.forEach(person => {
-    if (person.outputs) {
-      console.log('LinkedIn:', person.inputs.linkedinUrl.value);
-      console.log('Emails:', person.outputs.emails);
-      console.log('Phones:', person.outputs.phoneNumbers);
-      console.log('---');
-    }
+      apiKey: process.env.FIBERAI_API_KEY!,
+      personDetails: [
+        { linkedinUrl: { value: "https://www.linkedin.com/in/example1" } },
+        { linkedinUrl: { value: "https://www.linkedin.com/in/example2" } },
+      ],
+      enrichmentTypes: {
+        getWorkEmails: true,
+        getPersonalEmails: true,
+        getPhoneNumbers: true,
+      },
+    },
   });
+
+const taskId: string = start.data!.output.taskId;
+console.log(`Queued ${start.data!.output.numPeopleEnqueued} profiles`);
+
+let cursor: string | null | undefined = undefined;
+let done: boolean = false;
+
+while (!done) {
+  await new Promise<void>((resolve) => setTimeout(resolve, 10000));
+
+  const poll: Awaited<ReturnType<typeof pollBatchContactEnrichment>> =
+    await pollBatchContactEnrichment({
+      body: {
+        apiKey: process.env.FIBERAI_API_KEY!,
+        taskId,
+        cursor,
+        take: 100,
+      },
+    });
+
+  if (!poll.data) break;
+
+  for (const row of poll.data.output.pageResults) {
+    console.log(row.inputs.linkedinUrl.value, row.outputs?.emails);
+  }
+
+  done = poll.data.output.done;
+  cursor = poll.data.output.nextCursor ?? null;
+
+  // `nextCursor` may go null before `done` flips — pause and re-poll if so.
+  if (!done && !cursor) await new Promise<void>((r) => setTimeout(r, 5000));
 }
 ```
 
@@ -427,134 +498,76 @@ Get real-time data from LinkedIn with live scraping.
 #### Live Profile Enrichment
 
 ```typescript
-import { profileLiveEnrich } from '@fiberai/sdk';
+import { profileLiveEnrich } from "@fiberai/sdk";
 
 const profile = await profileLiveEnrich({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/in/example'
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    // `identifier` accepts a slug ('williamhgates'), a full LinkedIn URL,
+    // a Sales Navigator URN ('ACwAAA...'), or a numeric LinkedIn user ID.
+    identifier: "https://www.linkedin.com/in/example",
+  },
 });
 
-console.log(profile.data.output.name);
-console.log(profile.data.output.summary);
-console.log(profile.data.output.experiences);
-console.log(profile.data.output.education);
+// `output` is a discriminated union: { found: true; profile: ... } |
+// { found: false; message: string }. Narrow on `output.found` before
+// touching `output.profile`.
+const out = profile.data?.output;
+if (out?.found) {
+  console.log(out.profile.name);
+  console.log(out.profile.summary);
+  console.log(out.profile.experiences);
+  console.log(out.profile.detailed_education);
+} else if (out) {
+  console.warn("not found:", out.message);
+}
 ```
 
 #### Live Company Enrichment
 
 ```typescript
-import { companyLiveEnrich } from '@fiberai/sdk';
+import { companyLiveEnrich } from "@fiberai/sdk";
 
 const company = await companyLiveEnrich({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/company/example'
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    // The `type` discriminator picks how `value` is interpreted:
+    //   'slug'   — LinkedIn slug, e.g. 'microsoft'
+    //   'orgId'  — LinkedIn organization id, e.g. '1441'
+    //   'liUrl'  — full LinkedIn URL, e.g. 'https://www.linkedin.com/company/microsoft'
+    type: "liUrl",
+    value: "https://www.linkedin.com/company/example",
+  },
 });
 
-console.log(company.data.output.preferred_name);
-console.log(company.data.output.li_description);
-console.log(company.data.output.li_follower_count);
+// Company fields live under `output.company`, not directly on `output`.
+console.log(company.data?.output.company.headline);
+console.log(company.data?.output.company.description);
+console.log(company.data?.output.company.follower_count);
 ```
 
 #### Fetch LinkedIn Posts
 
 ```typescript
-import { profilePostsLiveFetch, companyPostsLiveFetch } from '@fiberai/sdk';
+import { profilePostsLiveFetch, companyPostsLiveFetch } from "@fiberai/sdk";
 
-// Get profile posts
+// Get profile posts. `identifier` accepts a slug, full LinkedIn URL,
+// or Sales Navigator URN — same shape as `profileLiveEnrich`.
 const profilePosts = await profilePostsLiveFetch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/in/example',
-    cursor: null // For pagination
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    identifier: "https://www.linkedin.com/in/example",
+    cursor: null, // For pagination
+  },
 });
 
-// Get company posts
+// Get company posts. `identifier` accepts a LinkedIn slug, URL, or org ID.
 const companyPosts = await companyPostsLiveFetch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    linkedinUrl: 'https://www.linkedin.com/company/example',
-    cursor: null
-  }
-});
-```
-
-### Saved Searches (Audiences)
-
-Create, manage, and run saved searches with automatic updates.
-
-```typescript
-import {
-  createSavedSearch,
-  listSavedSearch,
-  manuallySpawnSavedSearchRun,
-  getSavedSearchRunStatus,
-  getSavedSearchRunCompanies,
-  getSavedSearchRunProfiles
-} from '@fiberai/sdk';
-
-// Create a saved search
-const savedSearch = await createSavedSearch({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    name: 'Tech Executives in SF',
-    searchParams: {
-      companySearchParams: {
-        industriesV2: {
-          anyOf: ['Software']
-        }
-      },
-      personSearchParams: {
-        title: ['CEO', 'CTO'],
-        seniority: ['Executive']
-      }
-    }
-  }
-});
-
-// List all saved searches
-const searches = await listSavedSearch({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY
-  }
-});
-
-// Manually run a saved search
-const run = await manuallySpawnSavedSearchRun({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    savedSearchId: savedSearch.data.output.savedSearchId
-  }
-});
-
-// Check run status
-const status = await getSavedSearchRunStatus({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    runId: run.data.output.runId
-  }
-});
-
-// Get companies from run
-const companies = await getSavedSearchRunCompanies({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    runId: run.data.output.runId,
-    pageSize: 100
-  }
-});
-
-// Get profiles from run
-const profiles = await getSavedSearchRunProfiles({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    runId: run.data.output.runId,
-    pageSize: 100
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    identifier: "https://www.linkedin.com/company/example",
+    cursor: null,
+  },
 });
 ```
 
@@ -567,16 +580,16 @@ import {
   createCompanyExclusionList,
   addCompaniesToExclusionList,
   getExcludedCompaniesForExclusionList,
-  createCompanyExclusionListFromAudience
-} from '@fiberai/sdk';
+  createCompanyExclusionListFromAudience,
+} from "@fiberai/sdk";
 
 // Create an exclusion list
 const list = await createCompanyExclusionList({
   body: {
     apiKey: process.env.FIBERAI_API_KEY,
-    name: 'Competitors',
-    isOrganizationWide: true
-  }
+    name: "Competitors",
+    isOrganizationWide: true,
+  },
 });
 
 // Add companies to the list
@@ -585,20 +598,20 @@ await addCompaniesToExclusionList({
     apiKey: process.env.FIBERAI_API_KEY,
     listId: list.data.output.listId,
     companies: [
-      { domain: 'competitor1.com', linkedinUrl: null },
-      { domain: 'competitor2.com', linkedinUrl: null }
-    ]
-  }
+      { domain: "competitor1.com", linkedinUrl: null },
+      { domain: "competitor2.com", linkedinUrl: null },
+    ],
+  },
 });
 
 // Create exclusion list from an existing audience
 const audienceList = await createCompanyExclusionListFromAudience({
   body: {
     apiKey: process.env.FIBERAI_API_KEY,
-    audienceId: 'audience-123',
-    name: 'Existing Customers',
-    isOrganizationWide: true
-  }
+    audienceId: "audience-123",
+    name: "Existing Customers",
+    isOrganizationWide: true,
+  },
 });
 
 // View excluded companies
@@ -606,8 +619,8 @@ const excluded = await getExcludedCompaniesForExclusionList({
   body: {
     apiKey: process.env.FIBERAI_API_KEY,
     exclusionListId: list.data.output.listId,
-    pageSize: 100
-  }
+    pageSize: 100,
+  },
 });
 ```
 
@@ -619,41 +632,54 @@ Search for local businesses on Google Maps.
 import {
   googleMapsSearch,
   checkGoogleMapsResults,
-  pollGoogleMapsResults
-} from '@fiberai/sdk';
+  pollGoogleMapsResults,
+} from "@fiberai/sdk";
 
-// Start Google Maps search
+// Start Google Maps search. `query` is the keywords only (no location info)
+// and `strategy` is required — see below for the available strategies.
 const search = await googleMapsSearch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    query: 'coffee shops',
-    location: 'San Francisco, CA',
-    maxResults: 100
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    query: "coffee shops",
+    maxResults: 100,
+    strategy: {
+      // Options:
+      //   { strategy: 'whole-usa' }
+      //   { strategy: 'specific-areas', unionAll: [{ regionType: 'circle', center: {latitude, longitude}, radiusMiles }] }
+      //   { strategy: 'world-cities', countriesAndRegions: { unionAll: ['USA', 'GBR', ...] } }
+      strategy: "specific-areas",
+      unionAll: [
+        {
+          regionType: "circle",
+          center: { latitude: 37.7749, longitude: -122.4194 },
+          radiusMiles: 10,
+        },
+      ],
+    },
+  },
 });
 
-// Check search progress
+const searchID = search.data!.output.searchID;
+
+// Check search progress.
 const progress = await checkGoogleMapsResults({
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    searchID: search.data.output.projectID
-  }
+  body: { apiKey: process.env.FIBERAI_API_KEY!, searchID },
 });
 
-console.log(`Progress: ${progress.data.output.percentageCompleted}%`);
+console.log(`Progress: ${progress.data?.output.percentageCompleted}%`);
 
-// Poll for results when complete
-if (progress.data.output.status === 'COMPLETED') {
+// Poll for results once complete.
+if (progress.data?.output.status === "COMPLETED") {
   const results = await pollGoogleMapsResults({
     body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      projectID: search.data.output.projectID,
-      pageSize: 50
-    }
+      apiKey: process.env.FIBERAI_API_KEY!,
+      searchID,
+      pageSize: 50,
+    },
   });
-  
-  results.data.output.results.forEach(place => {
-    console.log(`${place.name} - ${place.address}`);
+
+  results.data?.output.results.forEach((place) => {
+    console.log(`${place.name} — ${place.address}`);
     console.log(`Rating: ${place.rating}, Reviews: ${place.numReviews}`);
     console.log(`Website: ${place.website}`);
   });
@@ -665,37 +691,42 @@ if (progress.data.output.status === 'COMPLETED') {
 Use AI agents for intelligent company research and domain lookup.
 
 ```typescript
-import { domainLookupTrigger, domainLookupPolling } from '@fiberai/sdk';
+import { domainLookupTrigger, domainLookupPolling } from "@fiberai/sdk";
 
-// Trigger domain lookup for company names
+// Trigger domain lookup. `overAllContext` is required and helps the agent
+// disambiguate similar names; `companyInfo` is an array of objects (not
+// a list of bare strings).
 const lookup = await domainLookupTrigger({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    companyNames: [
-      'OpenAI',
-      'Anthropic',
-      'Stripe'
-    ]
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    overAllContext: "YC startups in the US",
+    companyInfo: [
+      { name: "Acme Corp" },
+      { name: "Globex", country: "USA" },
+      { name: "Initech" },
+    ],
+  },
 });
 
-// Poll for results
+const domainAgentRunId = lookup.data!.output.domainAgentRunId;
+
+// Poll for results.
 let lookupDone = false;
 while (!lookupDone) {
-  await new Promise(resolve => setTimeout(resolve, 3000));
-  
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+
   const results = await domainLookupPolling({
     body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      domainAgentRunId: lookup.data.output.domainAgentRunId,
-      pageSize: 10
-    }
+      apiKey: process.env.FIBERAI_API_KEY!,
+      domainAgentRunId,
+      pageSize: 10,
+    },
   });
-  
-  lookupDone = results.data.output.status === 'DONE';
-  
+
+  lookupDone = results.data?.output.status === "DONE";
+
   if (lookupDone) {
-    results.data.output.data.forEach(company => {
+    results.data?.output.data.forEach((company) => {
       console.log(`${company.companyName}: ${company.bestDomain}`);
       console.log(`Confidence: ${company.confidence}/10`);
       console.log(`Rationale: ${company.rationale}`);
@@ -706,53 +737,62 @@ while (!lookupDone) {
 
 ## Advanced Usage
 
-### Custom Client Configuration
+### Configuring the built-in client
+
+The SDK exports a pre-configured `client` that already points at `https://api.fiber.ai`. Every operation uses it by default — you do **not** need to call `createClient` to make requests.
+
+If you need to customize headers, swap in a custom `fetch`, or add request/response interceptors, mutate the shared instance:
 
 ```typescript
-import { createClient } from '@fiberai/sdk';
+import { client } from "@fiberai/sdk";
 
-// Create a custom client
-const customClient = createClient({
-  baseUrl: 'https://api.fiber.ai', // Production URL
-  // Add custom headers, interceptors, etc.
+// One-time configuration: extra headers, a custom fetch, etc.
+client.setConfig({
+  headers: { "X-Trace-Id": "my-app/1.0.0" },
 });
 
-// Use with any SDK function
-import { companySearch } from '@fiberai/sdk';
-
-const result = await companySearch({
-  client: customClient,
-  body: { /* ... */ }
+// Log every outgoing request — handy as a poor man's debug mode.
+client.interceptors.request.use((request) => {
+  console.log(`[fiberai] ${request.method} ${request.url}`);
+  return request;
 });
 ```
 
+`createClient` from the package is for the rare case where you want a second, independent client (e.g. multi-tenant apps). Pass it via the `client:` option on any operation.
+
 ### Pagination Helper
 
 ```typescript
-async function* paginateSearch(searchFn, params) {
-  let cursor = null;
-  
+import type { CompanySearchData, CompanySearchResponse } from "@fiberai/sdk";
+
+async function* paginateCompanies(
+  initial: CompanySearchData,
+): AsyncGenerator<
+  NonNullable<CompanySearchResponse["data"]>["output"]["data"]
+> {
+  let cursor: string | null | undefined = initial.body.cursor ?? null;
+
   do {
-    const result = await searchFn({
-      ...params,
-      body: {
-        ...params.body,
-        cursor
-      }
+    const result = await companySearch({
+      ...initial,
+      body: { ...initial.body, cursor },
     });
-    
-    yield result.data.output.data.items;
+
+    if (!result.data) break;
+    yield result.data.output.data;
     cursor = result.data.output.nextCursor;
   } while (cursor);
 }
 
 // Usage
-for await (const companies of paginateSearch(companySearch, {
+for await (const companies of paginateCompanies({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    searchParams: { /* ... */ },
-    pageSize: 100
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    searchParams: {
+      /* ... */
+    },
+    pageSize: 100,
+  },
 })) {
   console.log(`Processing batch of ${companies.length} companies`);
   // Process batch
@@ -769,22 +809,22 @@ import {
   getIndustries,
   getTags,
   getNaicsCodes,
-  getAccelerators
-} from '@fiberai/sdk';
+  getAccelerators,
+} from "@fiberai/sdk";
 
 // Get available regions for filtering
 const regions = await getRegions({
-  query: { apiKey: process.env.FIBERAI_API_KEY }
+  query: { apiKey: process.env.FIBERAI_API_KEY },
 });
 
 // Get available industries
 const industries = await getIndustries({
-  query: { apiKey: process.env.FIBERAI_API_KEY }
+  query: { apiKey: process.env.FIBERAI_API_KEY },
 });
 
 // Get profile and company tags
 const tags = await getTags({
-  query: { apiKey: process.env.FIBERAI_API_KEY }
+  query: { apiKey: process.env.FIBERAI_API_KEY },
 });
 ```
 
@@ -792,28 +832,44 @@ const tags = await getTags({
 
 ### Standard Error Handling
 
+By default, every operation returns `{ data, error, response }`. Branch on the HTTP status from `response.status` rather than string-matching the error body — error payloads are not guaranteed to contain a parseable `message` for every failure mode.
+
 ```typescript
-import { companySearch } from '@fiberai/sdk';
+import { companySearch } from "@fiberai/sdk";
 
 const result = await companySearch({
   body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    searchParams: { /* ... */ }
-  }
+    apiKey: process.env.FIBERAI_API_KEY!,
+    searchParams: {
+      /* ... */
+    },
+  },
 });
 
 if (result.error) {
-  console.error('API Error:', result.error);
-  // Handle specific error codes
-  if (result.error.message.includes('401')) {
-    console.error('Invalid API key');
-  } else if (result.error.message.includes('402')) {
-    console.error('Insufficient credits');
-  } else if (result.error.message.includes('429')) {
-    console.error('Rate limit exceeded');
+  switch (result.response.status) {
+    case 400:
+      console.error("Bad request:", result.error);
+      break;
+    case 401:
+      console.error("Invalid API key");
+      break;
+    case 402:
+      // 402 errors carry an `outOfCreditsAlert` with a top-up link.
+      console.error("Insufficient credits:", result.error);
+      break;
+    case 429:
+      console.error("Rate limit exceeded — back off and retry");
+      break;
+    default:
+      console.error(
+        `Request failed (${result.response.status}):`,
+        result.error,
+      );
   }
 } else {
-  console.log('Success:', result.data);
+  console.log("Success:", result.data?.output);
+  console.log("Charged:", result.data?.chargeInfo);
 }
 ```
 
@@ -821,86 +877,109 @@ if (result.error) {
 
 ```typescript
 try {
-  const result = await companySearch<true>({
+  const result = await companySearch({
     body: {
-      apiKey: process.env.FIBERAI_API_KEY,
-      searchParams: { /* ... */ }
+      apiKey: process.env.FIBERAI_API_KEY!,
+      searchParams: {
+        /* ... */
+      },
     },
-    throwOnError: true
+    throwOnError: true,
   });
-  
-  // result.data is guaranteed to exist
+
+  // result.data is guaranteed to exist when throwOnError is true.
   console.log(result.data.output);
 } catch (error) {
-  console.error('Request failed:', error);
+  console.error("Request failed:", error);
 }
 ```
 
 ### Common HTTP Error Codes
 
-| Code | Meaning | Solution |
-|------|---------|----------|
-| 400 | Bad Request | Check your request parameters |
-| 401 | Unauthorized | Verify your API key is valid |
-| 402 | Payment Required | Insufficient credits - top up your account |
-| 403 | Forbidden | You don't have access to this resource |
-| 404 | Not Found | Resource doesn't exist |
-| 429 | Too Many Requests | Rate limit exceeded - slow down requests |
-| 500 | Internal Server Error | Contact support |
+| Code | Meaning               | Solution                                   |
+| ---- | --------------------- | ------------------------------------------ |
+| 400  | Bad Request           | Check your request parameters              |
+| 401  | Unauthorized          | Verify your API key is valid               |
+| 402  | Payment Required      | Insufficient credits - top up your account |
+| 403  | Forbidden             | You don't have access to this resource     |
+| 404  | Not Found             | Resource doesn't exist                     |
+| 429  | Too Many Requests     | Rate limit exceeded - slow down requests   |
+| 500  | Internal Server Error | Contact support                            |
 
 ## TypeScript Support
 
 All SDK methods are fully typed with TypeScript.
 
 ```typescript
-import type {
-  CompanySearchData,
-  CompanySearchResponse,
-  PeopleSearchData,
-  PeopleSearchResponse,
-  TriggerContactEnrichmentData,
-  PollContactEnrichmentResultResponse
-} from '@fiberai/sdk';
-
-// Type-safe request
-const searchParams: CompanySearchData = {
+import { companySearch } from "@fiberai/sdk";
+
+// SDK functions return `{ data, error, response }`. Annotate the awaited call
+// with `Awaited<ReturnType<typeof fn>>` — the exported `<Op>Response` /
+// `<Op>Errors` types describe the inner body union, NOT the wrapper.
+const result: Awaited<ReturnType<typeof companySearch>> = await companySearch({
   body: {
     apiKey: process.env.FIBERAI_API_KEY!,
     searchParams: {
-      industriesV2: {
-        anyOf: ['Software']
-      },
+      industriesV2: { anyOf: ["Software"] },
       employeeCountV2: {
-        lowerBoundExclusive: 100,
-        upperBoundInclusive: 1000
-      }
+        lowerBoundExclusive: 50,
+        upperBoundInclusive: 1000,
+      },
     },
-    pageSize: 25
-  }
-};
+    pageSize: 25,
+  },
+});
+
+if (result.data) {
+  console.log(`${result.data.output.data.length} companies`);
+  console.log(result.data.chargeInfo);
+}
 
-const result: CompanySearchResponse = await companySearch(searchParams);
+// Need a name for the request shape (e.g. building a request in one place,
+// passing it elsewhere)? Derive it from the function — the bare `<Op>Data`
+// export carries an internal `url` literal and is not meant to be
+// hand-constructed.
+type CompanySearchArgs = Parameters<typeof companySearch>[0];
 ```
 
-### Runtime Validation
+> **Naming convention:** every operation `foo` ships companion types:
+> `FooResponse` (200 body union) and `FooErrors` (4xx/5xx body union). Use `Parameters<typeof foo>[0]` for input args and `Awaited<ReturnType<typeof foo>>` for the result envelope. The same applies to `peopleSearch`, `syncQuickContactReveal`, etc.
+
+### Runtime Validation with Zod
 
-The SDK includes Zod schemas for runtime validation. Zod is included automatically with the SDK installation.
+Every request and response shape is also published as a [Zod](https://zod.dev) schema, generated from the same OpenAPI spec as the TypeScript types. They live behind the dedicated `@fiberai/sdk/zod` subpath so apps that don't need runtime validation pay zero bundle cost — the main entry stays under 50 KB while the Zod bundle (~3–6 MB depending on the API surface) is only loaded if you import it.
 
 ```typescript
-import { z } from 'zod';
-import { zCompanySearchData } from '@fiberai/sdk/dist/generated/zod.gen';
+import { zPeopleSearchData, zCompanySearchData } from "@fiberai/sdk/zod";
+import { peopleSearch } from "@fiberai/sdk";
 
-const requestData = {
-  body: {
-    apiKey: process.env.FIBERAI_API_KEY,
-    searchParams: { /* ... */ }
-  }
-};
+const rawInput: unknown = JSON.parse(req.body);
+
+const parsed: ReturnType<typeof zPeopleSearchData.parse> =
+  zPeopleSearchData.parse(rawInput);
+
+const result: Awaited<ReturnType<typeof peopleSearch>> =
+  await peopleSearch(parsed);
+```
+
+Use `safeParse` if you want to handle validation failures without throwing. Zod 4 ships top-level error helpers — use `z.flattenError` for form-friendly output or `z.treeifyError` for nested shapes:
+
+```typescript
+import { z } from "zod";
+import { zCompanySearchData } from "@fiberai/sdk/zod";
 
-// Validate at runtime
-const validatedData = zCompanySearchData.parse(requestData);
+const parsed: ReturnType<typeof zCompanySearchData.safeParse> =
+  zCompanySearchData.safeParse(req.body);
+
+if (!parsed.success) {
+  return res.status(400).json({ errors: z.flattenError(parsed.error) });
+}
 ```
 
+> **Naming convention:** every TypeScript type `Foo` has a matching `zFoo` schema. So `PeopleSearchData` ↔ `zPeopleSearchData`, `CompanySearchResponse` ↔ `zCompanySearchResponse`, etc.
+
+`zod` ships as a runtime dependency of `@fiberai/sdk` and is externalized from the bundle (so package managers dedupe with whatever Zod copy your app already has). If you don't import `@fiberai/sdk/zod`, your bundler tree-shakes the schemas out and you never pay for them.
+
 ## Rate Limits & Credits
 
 ### Rate Limits
@@ -914,43 +993,44 @@ Each endpoint has its own rate limit. Common limits:
 
 ### Credit Costs
 
-**Default pricing** (may vary - check your organization settings):
-
-| Operation | Cost (credits) |
-|-----------|----------------|
-| Company search | 1 per company found |
-| People search | 1 per profile found |
-| Combined search | 1 per company + 1 per profile |
-| Work email reveal | 2 |
-| Personal email reveal | 2 |
-| Phone number reveal | 3 |
-| All contact data | 5 |
-| Live profile enrichment | 2 |
-| Live company enrichment | 2 |
-| LinkedIn posts (per page) | 2 |
-| Google Maps search | 3 per result |
+Pricing varies by plan and is configured per-organization. **Don't hard-code costs into your app** — every successful response carries a `chargeInfo` envelope alongside `output` that tells you exactly what was charged for that call:
+
+```typescript
+const result = await peopleSearch({
+  /* ... */
+});
+
+console.log(result.data?.chargeInfo);
+// {
+//   method: 'charged-now',          // 'charged-now' | 'charging-later' | 'charged-for-async-process' | 'free'
+//   creditsCharged: 25,             // present when method !== 'free'
+//   lowCreditAlert: null            // populated with a top-up URL when running low
+// }
+```
+
+For a non-charging dry-run estimate of contact enrichment costs, use [`estimateEnrichmentCost`](https://api.fiber.ai/ai-docs/estimateEnrichmentCost.md). For the per-org pricing breakdown across operations, inspect `getOrgCredits().data.output.creditsPerOperation`.
 
 ### Free Endpoints
 
-The following endpoints are **completely free** (no credits charged):
+The following endpoints never charge credits:
 
-- `getOrgCredits` - Check credit balance
-- `getRegions`, `getLanguages`, `getTimeZones`, `getIndustries`, `getTags`, `getNaicsCodes`, `getAccelerators` - Utility endpoints
-- All exclusion list management endpoints
+- `getOrgCredits` — Check credit balance
+- `getRegions`, `getLanguages`, `getTimeZones`, `getIndustries`, `getTags`, `getNaicsCodes`, `getAccelerators` — Utility endpoints
+- All exclusion-list management endpoints
 
 ### Check Your Credits
 
 ```typescript
-import { getOrgCredits } from '@fiberai/sdk';
+import { getOrgCredits } from "@fiberai/sdk";
 
 const credits = await getOrgCredits({
-  query: { apiKey: process.env.FIBERAI_API_KEY }
+  query: { apiKey: process.env.FIBERAI_API_KEY! },
 });
 
-console.log(`Available: ${credits.data.output.available}`);
-console.log(`Used: ${credits.data.output.used}`);
-console.log(`Max: ${credits.data.output.max}`);
-console.log(`Resets on: ${credits.data.output.usagePeriodResetsOn}`);
+console.log(`Available: ${credits.data?.output.available}`);
+console.log(`Used: ${credits.data?.output.used}`);
+console.log(`Max: ${credits.data?.output.max}`);
+console.log(`Resets on: ${credits.data?.output.usagePeriodResetsOn}`);
 ```
 
 ## Support