orangeslice 1.7.21 → 1.8.0

package/README.md

@@ -1,164 +1,93 @@
 # orangeslice
 
-B2B LinkedIn database prospector. **1.15B profiles, 85M companies.**
+Orangeslice provides a `services.*` API for B2B research, enrichment, scraping, and AI helpers.
+
+## Quick start
 
 ```bash
 npx orangeslice
 ```
 
-This installs documentation your AI agent needs to master the database. Point your agent (Claude Code, Cursor, etc.) to `./AGENTS.md` and it becomes a B2B prospecting expert.
-
-For maintainers: npm publishes docs from the canonical source at `../lib/vfs/sheet-chat` via `npm run sync-docs`, so the app docs and package docs stay in sync.
-
-## What It Does
-
-Your AI agent gets:
-- Full database schema (40+ tables)
-- Query patterns and examples
-- Anti-patterns to avoid
-- Performance rules
-- **Parallelization patterns** — agents must run queries in parallel, never sequentially
-- **AI structured output** — extract structured data from text with `orangeslice.ai.generateObject()`
-
-## 🚨 CRITICAL: Always Parallelize
+The CLI copies docs to `./orangeslice-docs` and creates `./orangeslice-docs/AGENTS.md` so Claude Code/Cursor can use the docs as source of truth.
 
-**The #1 rule: NEVER run queries sequentially. ALWAYS use `Promise.all()`.**
-
-The API handles rate limiting automatically. Fire all queries at once.
-
-```typescript
-// ❌ WRONG - Sequential (SLOW)
-const company = await orangeslice.b2b.sql("...");
-const funding = await orangeslice.b2b.sql("...");
-const jobs = await orangeslice.b2b.sql("...");
-
-// ✅ CORRECT - Parallel (FAST)
-const [company, funding, jobs] = await Promise.all([
-  orangeslice.b2b.sql("..."),
-  orangeslice.b2b.sql("..."),
-  orangeslice.b2b.sql("..."),
-]);
-```
-
-## Quick Example
-
-```typescript
-import { orangeslice } from 'orangeslice';
-
-// Research a company - ALL queries in parallel
-const [company, funding, recentJobs, leadership] = await Promise.all([
-  orangeslice.b2b.sql(`SELECT * FROM linkedin_company WHERE domain = 'stripe.com'`),
-  orangeslice.b2b.sql(`SELECT * FROM linkedin_crunchbase_funding WHERE linkedin_company_id = 123`),
-  orangeslice.b2b.sql(`SELECT * FROM linkedin_job WHERE linkedin_company_id = 123 LIMIT 10`),
-  orangeslice.b2b.sql(`
-    SELECT p.first_name, p.last_name, pos.title
-    FROM linkedin_profile p
-    JOIN linkedin_profile_position3 pos ON pos.linkedin_profile_id = p.id
-    WHERE pos.linkedin_company_id = 123 AND pos.end_date IS NULL
-    LIMIT 10
-  `),
-]);
-
-// Research multiple companies - ALL in parallel
-const domains = ['stripe.com', 'openai.com', 'anthropic.com'];
-const companies = await Promise.all(
-  domains.map(d => orangeslice.b2b.sql(`SELECT * FROM linkedin_company WHERE domain = '${d}'`))
-);
-```
-
-## Documentation
-
-After running `npx orangeslice`, you get:
-
-```
-orangeslice-docs/
-├── AGENTS.md              # Agent instructions (includes parallelization rules)
-└── linkedin_data/
-    ├── QUICK_REF.md       # START HERE - Critical rules & patterns
-    ├── tables/            # Full schema (denormalized + normalized)
-    └── search_examples/   # Query patterns for people & companies
-```
-
-**Read `linkedin_data/QUICK_REF.md` before writing any queries.**
-
-## Installation
+Install as a dependency when writing app code:
 
 ```bash
 npm install orangeslice
 ```
 
-## API
-
-### `orangeslice.b2b.sql<T>(query: string): Promise<T>`
-
-Execute SQL and return rows. **Always wrap multiple calls in `Promise.all()`.**
-
-```typescript
-// Single query
-const companies = await orangeslice.b2b.sql<Company[]>(
-  "SELECT * FROM linkedin_company WHERE employee_count > 1000 LIMIT 10"
-);
-
-// Multiple queries - ALWAYS parallel
-const [techCos, healthCos, financeCos] = await Promise.all([
-  orangeslice.b2b.sql("SELECT * FROM linkedin_company WHERE industry_code = 4 LIMIT 10"),
-  orangeslice.b2b.sql("SELECT * FROM linkedin_company WHERE industry_code = 14 LIMIT 10"),
-  orangeslice.b2b.sql("SELECT * FROM linkedin_company WHERE industry_code = 43 LIMIT 10"),
+## Public API (services-first)
+
+Use `services.*` as the primary API surface.
+
+```ts
+import { services } from "orangeslice";
+
+const [companies, searchPage, ai] = await Promise.all([
+   services.company.linkedin.search({
+      sql: "SELECT * FROM linkedin_company WHERE domain = 'stripe.com' LIMIT 5"
+   }),
+   services.web.search({ query: "site:linkedin.com/company stripe" }),
+   services.ai.generateObject({
+      prompt: "Extract company and founding year from: Stripe was founded in 2010.",
+      schema: {
+         type: "object",
+         properties: {
+            company: { type: "string" },
+            year: { type: "number" }
+         },
+         required: ["company", "year"]
+      }
+   })
 ]);
 ```
 
-### `orangeslice.b2b.query<T>(query: string): Promise<QueryResult<T>>`
-
-Execute SQL and return full result with metadata.
+## Service map
 
-```typescript
-const result = await orangeslice.b2b.query("SELECT * FROM linkedin_company LIMIT 10");
-// result.rows, result.rowCount, result.duration_ms
-```
+- `services.company.linkedin.search/findUrl/enrich`
+- `services.person.linkedin.search/findUrl/enrich`
+- `services.person.contact.get`
+- `services.company.getEmployeesFromLinkedin`
+- `services.web.search/batchSearch`
+- `services.ai.generateObject`
+- `services.scrape.website`
+- `services.browser.execute`
+- `services.apify.runActor`
+- `services.googleMaps.scrape`
+- `services.geo.parseAddress`
+- `services.healthcare.npi`
+- `services.builtWith.lookupDomain/relationships/searchByTech`
 
-### `orangeslice.b2b.configure(options)`
+## How routing works today
 
-Configure rate limiting. Default settings handle parallelization automatically.
+All service calls go through `post()` in `src/api.ts`.
 
-```typescript
-orangeslice.b2b.configure({
-  concurrency: 3,      // default: 2 concurrent requests
-  minDelayMs: 200,     // default: 100ms between requests
-});
-```
+- Default path: `https://enrichly-production.up.railway.app/function`
+- Direct path: `https://orangeslice.ai/api/function` (only when a call passes `direct: true`)
+- Polling split for pending/`202`:
+  - `batch-native` (`b2b`, `batchserp`, `generateObject`) polls batch-service result endpoint.
+  - `bridge` functions poll `https://orangeslice.ai/api/function/bridge-result`.
+- Inngest secrets are server-side only (Next.js route env vars), never in the npm package.
 
-### `orangeslice.ai.generateObject<T>(options): Promise<T>`
-
-Generate structured data from text using AI.
-
-```typescript
-const result = await orangeslice.ai.generateObject({
-  prompt: "Extract company info: Stripe was founded in 2010 by Patrick Collison",
-  schema: {
-    type: "object",
-    properties: {
-      company: { type: "string" },
-      year: { type: "number" },
-      founder: { type: "string" }
-    },
-    required: ["company", "year"]
-  }
-});
-// { company: "Stripe", year: 2010, founder: "Patrick Collison" }
-```
+The current endpoint-to-backend mapping is documented in `docs/runtime-routing.md`.
 
-### `orangeslice.ai.extract<T>(text, schema, instructions?): Promise<T>`
+## Docs installed by CLI
 
-Convenience method to extract structured data from text.
+After `npx orangeslice`, you should have:
 
-```typescript
-const data = await orangeslice.ai.extract(
-  "Apple Inc was founded in 1976 by Steve Jobs in Cupertino",
-  { type: "object", properties: { company: { type: "string" }, year: { type: "number" } } },
-  "Extract the company name and founding year"
-);
+```text
+orangeslice-docs/
+  AGENTS.md
+  services/
+  prospecting/
+  ...other synced docs
 ```
 
+## Maintainer notes
+
+- Canonical docs are synced from `../lib/vfs/sheet-chat` via `npm run sync-docs`.
+- `prepublishOnly` runs docs sync and TypeScript build.
+
 ## Restrictions
 
 - No direct contact data (email/phone)

package/dist/api.d.ts

@@ -1,5 +1,9 @@
+export type FunctionType = "batch-native" | "bridge";
+export declare const BATCH_NATIVE_FUNCTION_IDS: Set<string>;
 interface PostOptions {
     direct?: boolean;
 }
+export declare function getFunctionType(functionId: string): FunctionType;
+export declare function getBridgeResultEventName(functionId: string): string | undefined;
 export declare function post<T>(functionId: string, payload: Record<string, unknown>, options?: PostOptions): Promise<T>;
 export {};

package/dist/api.js

@@ -1,19 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BATCH_NATIVE_FUNCTION_IDS = void 0;
+exports.getFunctionType = getFunctionType;
+exports.getBridgeResultEventName = getBridgeResultEventName;
 exports.post = post;
+const crypto_1 = require("crypto");
 /**
- * Runtime routing (hardcoded on purpose):
- * - Non-direct calls -> Railway batch-service /function
- * - Direct calls     -> orangeslice.ai /api/function
- * - Inngest polling  -> batch-service (configured there)
+ * Runtime routing:
+ * - Non-direct calls submit to Railway batch-service /function
+ * - Direct calls submit to orangeslice.ai /api/function
+ * - Pending polling splits by function type:
+ *   - batch-native: poll batch-service /function/result
+ *   - bridge: poll Next.js bridge-result route (server-side Inngest key)
  */
 const BASE_URL = "https://enrichly-production.up.railway.app/function";
 const DIRECT_BASE_URL = "https://orangeslice.ai/api/function";
+const BRIDGE_POLL_URL = "https://orangeslice.ai/api/function/bridge-result";
 const POLL_TIMEOUT_MS = 120000;
 const DEFAULT_POLL_INTERVAL_MS = 1000;
+const INTERNAL_CALLBACK_ID_KEY = "_orangesliceCallbackEventId";
+exports.BATCH_NATIVE_FUNCTION_IDS = new Set(["b2b", "batchserp", "generateObject"]);
+const BRIDGE_RESULT_EVENT_BY_FUNCTION_ID = {
+    firecrawl: "proxy/firecrawl.result",
+    kernel: "proxy/kernel.result",
+    apify: "proxy/apify.result",
+    contact: "proxy/invoke.result",
+    "linkedin/find-profile-url": "proxy/linkedin-profile-url.result",
+    "find-linkedin-company-url": "proxy/linkedin-company-url.result",
+    "b2b-get-employees-for-company": "proxy/invoke.result",
+    geo: "proxy/invoke.result",
+    npi: "proxy/invoke.result",
+    googleMaps: "proxy/invoke.result",
+    builtwithLookupDomain: "proxy/invoke.result",
+    builtwithRelationships: "proxy/invoke.result",
+    builtwithSearchByTech: "proxy/invoke.result",
+};
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getFunctionType(functionId) {
+    return exports.BATCH_NATIVE_FUNCTION_IDS.has(functionId) ? "batch-native" : "bridge";
+}
+function getBridgeResultEventName(functionId) {
+    return BRIDGE_RESULT_EVENT_BY_FUNCTION_ID[functionId];
+}
 async function readResponseBody(res) {
     const text = await res.text();
     if (!text)
@@ -53,7 +83,7 @@ function isPendingResponse(body) {
         return false;
     return body.pending === true;
 }
-function resolvePollUrl(baseUrl, pending) {
+function resolveBatchPollUrl(baseUrl, pending) {
     if (pending.pollUrl) {
         return new URL(pending.pollUrl, baseUrl).toString();
     }
@@ -76,8 +106,8 @@ async function fetchWithRedirect(url, init) {
     }
     return res;
 }
-async function pollUntilComplete(baseUrl, functionId, pending) {
-    const pollUrl = resolvePollUrl(baseUrl, pending);
+async function pollBatchUntilComplete(baseUrl, functionId, pending) {
+    const pollUrl = resolveBatchPollUrl(baseUrl, pending);
     const timeoutAt = Date.now() + POLL_TIMEOUT_MS;
     let pollAfterMs = typeof pending.pollAfterMs === "number" && pending.pollAfterMs > 0
         ? pending.pollAfterMs
@@ -103,10 +133,39 @@ async function pollUntilComplete(baseUrl, functionId, pending) {
     }
     throw new Error(`[orangeslice] ${functionId}: polling timed out after ${POLL_TIMEOUT_MS}ms`);
 }
+async function pollBridgeUntilComplete(functionId, callbackEventId, eventName, firstPollAfterMs) {
+    const timeoutAt = Date.now() + POLL_TIMEOUT_MS;
+    let pollAfterMs = typeof firstPollAfterMs === "number" && firstPollAfterMs > 0 ? firstPollAfterMs : DEFAULT_POLL_INTERVAL_MS;
+    while (Date.now() < timeoutAt) {
+        await sleep(pollAfterMs);
+        const url = `${BRIDGE_POLL_URL}?callbackEventId=${encodeURIComponent(callbackEventId)}&eventName=${encodeURIComponent(eventName)}`;
+        const res = await fetch(url, { method: "GET", headers: { "Content-Type": "application/json" } });
+        const data = await readResponseBody(res);
+        if (isPendingResponse(data) || res.status === 202) {
+            const next = data.pollAfterMs;
+            pollAfterMs = typeof next === "number" && next > 0 ? next : DEFAULT_POLL_INTERVAL_MS;
+            continue;
+        }
+        if (!res.ok) {
+            const message = asErrorMessage(data) || JSON.stringify(data);
+            throw new Error(`[orangeslice] ${functionId}: ${res.status} ${message}`);
+        }
+        const message = asErrorMessage(data);
+        if (message) {
+            throw new Error(`[orangeslice] ${functionId}: ${message}`);
+        }
+        return data;
+    }
+    throw new Error(`[orangeslice] ${functionId}: bridge polling timed out after ${POLL_TIMEOUT_MS}ms`);
+}
 async function post(functionId, payload, options = {}) {
     const baseUrl = options.direct ? DIRECT_BASE_URL : BASE_URL;
+    const functionType = options.direct ? "batch-native" : getFunctionType(functionId);
+    const bridgeEventName = getBridgeResultEventName(functionId);
+    const callbackEventId = functionType === "bridge" && !options.direct && bridgeEventName ? (0, crypto_1.randomUUID)() : undefined;
+    const requestPayload = callbackEventId && functionType === "bridge" ? { ...payload, [INTERNAL_CALLBACK_ID_KEY]: callbackEventId } : payload;
     const url = `${baseUrl}?functionId=${functionId}`;
-    const body = JSON.stringify(payload);
+    const body = JSON.stringify(requestPayload);
     const res = await fetchWithRedirect(url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -120,7 +179,16 @@ async function post(functionId, payload, options = {}) {
     }
     const data = await readResponseBody(res);
     if (isPendingResponse(data)) {
-        return pollUntilComplete(baseUrl, functionId, data);
+        if (functionType === "bridge") {
+            const bridgePending = data;
+            const resolvedCallbackId = bridgePending.callbackEventId || callbackEventId;
+            const resolvedEventName = bridgePending.eventName || bridgeEventName;
+            if (!resolvedCallbackId || !resolvedEventName) {
+                throw new Error(`[orangeslice] ${functionId}: missing bridge callback metadata for polling`);
+            }
+            return pollBridgeUntilComplete(functionId, resolvedCallbackId, resolvedEventName, bridgePending.pollAfterMs);
+        }
+        return pollBatchUntilComplete(baseUrl, functionId, data);
     }
     const errorMessage = asErrorMessage(data);
     if (errorMessage) {

package/dist/cli.js

@@ -34,9 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 const LEGACY_DOCS_DIR = path.join(__dirname, "..", "docs");
 const TARGET_DIR = path.join(process.cwd(), "orangeslice-docs");
 const AGENTS_FILE = path.join(TARGET_DIR, "AGENTS.md");
@@ -69,7 +69,12 @@ function copyDirSync(src, dest) {
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
-        entry.isDirectory() ? copyDirSync(srcPath, destPath) : fs.copyFileSync(srcPath, destPath);
+        if (entry.isDirectory()) {
+            copyDirSync(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
     }
 }
 function writeAgentsGuide(destDir) {
@@ -95,7 +100,7 @@ Use the docs in this folder as the source of truth for all orangeslice operation
     fs.writeFileSync(AGENTS_FILE, content, "utf8");
 }
 async function main() {
-    console.log("\n🍊 orangeslice\n");
+    console.log("\norangeslice\n");
     const docsDir = resolveDocsDir();
     // Copy docs
     if (fs.existsSync(TARGET_DIR))
@@ -110,15 +115,19 @@ async function main() {
     catch {
         // no package.json or npm not available
     }
-    console.log("\n✅ Ready — services-style API\n");
+    console.log("\nReady - services-style API\n");
     console.log("  import { services } from 'orangeslice';\n");
-    console.log("  🤖 Agent setup (do this first):");
+    console.log("  Agent setup (do this first):");
     console.log("  Ask your agent to read:");
     console.log("    1) ./orangeslice-docs/AGENTS.md");
     console.log("    2) ./orangeslice-docs/services/index.md");
-    console.log("  Then tell it: \"Use these docs as source of truth for all orangeslice operations.\"\n");
+    console.log('  Then tell it: "Use these docs as source of truth for all orangeslice operations."\n');
+    console.log("  Routing note:");
+    console.log("    - LinkedIn SQL (functionId=b2b) is routed direct");
+    console.log("    - batch-native: b2b/batchserp/generateObject poll batch-service results");
+    console.log("    - bridge functions poll a server route (Inngest keys are server-side only)\n");
     console.log("  // LinkedIn B2B SQL");
-    console.log("  const { rows } = await services.company.linkedin.search({ sql: \"SELECT * FROM linkedin_company LIMIT 10\" });\n");
+    console.log('  const { rows } = await services.company.linkedin.search({ sql: "SELECT * FROM linkedin_company LIMIT 10" });\n');
     console.log("  // Web search");
     console.log("  const page = await services.web.search({ query: 'best CRM software' });\n");
     console.log("  // Batched web search");
@@ -126,9 +135,9 @@ async function main() {
     console.log("  // AI structured output");
     console.log("  const { object } = await services.ai.generateObject({ prompt: '...', schema: {...} });\n");
     console.log("  // Browser automation (Kernel)");
-    console.log("  const browser = await services.browser.execute({ code: \"return await page.title();\" });\n");
+    console.log('  const browser = await services.browser.execute({ code: "return await page.title();" });\n');
     console.log("  // Apify actor");
     console.log("  const actor = await services.apify.runActor({ actor: 'apify/web-scraper', input: {} });\n");
-    console.log("  ⚠️  Always parallelize independent calls with Promise.all.\n");
+    console.log("  Always parallelize independent calls with Promise.all.\n");
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orangeslice",
-  "version": "1.7.21",
+  "version": "1.8.0",
   "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",