orangeslice 1.6.0 → 1.7.0

package/README.md

@@ -56,6 +56,35 @@ All calls are rate-limited automatically.
 npm install orangeslice
 ```
 
+### TypeScript Setup
+
+If running `.ts` files directly with `ts-node` or `tsx`, you may need:
+
+```bash
+npm install -D typescript @types/node tsx
+```
+
+Recommended `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true
+  }
+}
+```
+
+Then run with:
+
+```bash
+npx tsx your-script.ts
+```
+
 ## Usage
 
 ```typescript
@@ -135,6 +164,42 @@ const result = await orangeslice.b2b.query("SELECT * FROM linkedin_company LIMIT
 // result.rows, result.rowCount, result.duration_ms
 ```
 
+### `orangeslice.serp.search(query: string, options?): Promise<SerpResponse>`
+
+Search Google and return results.
+
+```typescript
+const response = await orangeslice.serp.search("Stripe funding 2024");
+// response.results = [{ title, link, snippet }, ...]
+
+// With options
+const filtered = await orangeslice.serp.search("site:linkedin.com CEO", {
+  tbs: "qdr:m",  // Past month
+  page: 1
+});
+```
+
+### `orangeslice.firecrawl.scrape(url: string, limit?): Promise<FirecrawlResponse>`
+
+Scrape a website and get markdown + social URLs.
+
+```typescript
+const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
+// page.markdown, page.socialUrls
+```
+
+### `orangeslice.browser.execute(code: string, options?): Promise<BrowserResponse>`
+
+Execute Playwright code with `page` in scope.
+
+```typescript
+const response = await orangeslice.browser.execute(`
+  await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+  return await page.evaluate(() => document.title);
+`);
+// response.success, response.result
+```
+
 ## Note on Concurrency
 
 The rate limit is **per-process**. If you run multiple scripts simultaneously, each has its own queue. For most AI agent use cases (single script), this is fine.

package/dist/apify.d.ts

@@ -0,0 +1,57 @@
+export interface DatasetListParams {
+    limit?: number;
+    offset?: number;
+    clean?: boolean;
+    fields?: string[];
+    unwind?: string;
+}
+export interface ActorSearchResult {
+    actorId: string;
+    name: string;
+    username: string;
+    title: string;
+    description: string;
+    stats: Record<string, unknown>;
+    pricing: Record<string, unknown>;
+}
+export interface ActorInputSchema {
+    actor: string;
+    actId: string;
+    buildId: string;
+    inputSchema: Record<string, unknown> | null;
+    inputProperties: Record<string, unknown>;
+}
+/**
+ * Run an Apify actor and get results
+ *
+ * @example
+ * // Scrape Google Maps reviews
+ * const reviews = await apify.run("compass/crawler-google-places", {
+ *   searchStringsArray: ["restaurants in NYC"],
+ *   maxReviews: 10
+ * });
+ */
+export declare function run<T = unknown[]>(actor: string, input?: Record<string, unknown>, datasetListParams?: DatasetListParams): Promise<T>;
+/**
+ * Search for Apify actors by keyword
+ *
+ * @example
+ * const actors = await apify.search("linkedin scraper");
+ */
+export declare function search(query: string, limit?: number): Promise<{
+    actors: ActorSearchResult[];
+    total: number;
+}>;
+/**
+ * Get the input schema for an actor (to understand what params it accepts)
+ *
+ * @example
+ * const schema = await apify.getInputSchema("apify/web-scraper");
+ * console.log(schema.inputProperties);
+ */
+export declare function getInputSchema(actor: string): Promise<ActorInputSchema>;
+export declare const apify: {
+    run: typeof run;
+    search: typeof search;
+    getInputSchema: typeof getInputSchema;
+};

package/dist/apify.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apify = void 0;
+exports.run = run;
+exports.search = search;
+exports.getInputSchema = getInputSchema;
+const queue_1 = require("./queue");
+const API_URL = process.env.ORANGESLICE_API_URL?.replace(/\?.*/, "") + "?functionId=apify" ||
+    "https://orangeslice.ai/api/function?functionId=apify";
+// Rate limit: 2 concurrent, 500ms between requests (Apify runs can be expensive)
+const queue = (0, queue_1.createQueue)(2);
+const rateLimiter = (0, queue_1.createRateLimiter)(500);
+/**
+ * Helper to make POST request, handling redirects manually
+ */
+async function fetchWithRedirect(url, body) {
+    let response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        redirect: "manual",
+    });
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (location) {
+            response = await fetch(location, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+            });
+        }
+    }
+    return response;
+}
+/**
+ * Run an Apify actor and get results
+ *
+ * @example
+ * // Scrape Google Maps reviews
+ * const reviews = await apify.run("compass/crawler-google-places", {
+ *   searchStringsArray: ["restaurants in NYC"],
+ *   maxReviews: 10
+ * });
+ */
+async function run(actor, input = {}, datasetListParams = {}) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({
+                operation: "runActor",
+                actor,
+                input,
+                datasetListParams,
+            });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Apify run failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (data.error) {
+                throw new Error(`Apify error: ${data.error}`);
+            }
+            return data;
+        });
+    });
+}
+/**
+ * Search for Apify actors by keyword
+ *
+ * @example
+ * const actors = await apify.search("linkedin scraper");
+ */
+async function search(query, limit = 10) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({
+                operation: "searchActors",
+                query,
+                limit,
+            });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Apify search failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (data.error) {
+                throw new Error(`Apify error: ${data.error}`);
+            }
+            return data;
+        });
+    });
+}
+/**
+ * Get the input schema for an actor (to understand what params it accepts)
+ *
+ * @example
+ * const schema = await apify.getInputSchema("apify/web-scraper");
+ * console.log(schema.inputProperties);
+ */
+async function getInputSchema(actor) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({
+                operation: "getInputSchema",
+                actor,
+            });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Apify getInputSchema failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (data.error) {
+                throw new Error(`Apify error: ${data.error}`);
+            }
+            return data;
+        });
+    });
+}
+// Export as namespace
+exports.apify = {
+    run,
+    search,
+    getInputSchema,
+};

package/dist/cli.js

@@ -42,7 +42,7 @@ const TARGET_DIR = path.join(process.cwd(), "orangeslice-docs");
 const AGENTS_MD = path.join(DOCS_DIR, "AGENTS.md");
 const ROOT_AGENTS_MD = path.join(process.cwd(), "AGENTS.md");
 async function main() {
-    console.log("\n🍊 orangeslice - setting up sales agent for AI...\n");
+    console.log("\n🍊 orangeslice - setting up AI sales agent toolkit\n");
     // 1. Copy AGENTS.md to project root (for auto-detection by Claude Code, etc.)
     console.log("1. Installing AGENTS.md at project root...");
     if (fs.existsSync(AGENTS_MD)) {
@@ -50,7 +50,7 @@ async function main() {
         console.log("   ✓ AGENTS.md → ./AGENTS.md (auto-detected by AI agents)\n");
     }
     // 2. Copy full docs to orangeslice-docs/
-    console.log("2. Copying detailed documentation...");
+    console.log("2. Copying tool documentation...");
     if (!fs.existsSync(TARGET_DIR)) {
         fs.mkdirSync(TARGET_DIR, { recursive: true });
     }
@@ -61,6 +61,13 @@ async function main() {
         fs.copyFileSync(src, dest);
     }
     console.log(`   ✓ ${files.length} docs → ./orangeslice-docs/\n`);
+    console.log("   Docs created:");
+    console.log("   • AGENTS.md     - Main overview + quick APIs");
+    console.log("   • b2b.md        - LinkedIn database (1B+ profiles)");
+    console.log("   • serp.md       - Google dorking cheatsheet");
+    console.log("   • browser.md    - Playwright automation");
+    console.log("   • apify.md      - Pre-built web scrapers");
+    console.log("   • strategies.md - Prospecting & enrichment patterns\n");
     // 3. Install package
     console.log("3. Installing orangeslice package...");
     try {
@@ -71,10 +78,14 @@ async function main() {
     }
     // 4. Done
     console.log("\n✅ Done! Your AI agent is now a sales research assistant.\n");
-    console.log("   AGENTS.md is at your project root - Claude Code will auto-detect it.\n");
-    console.log("   Your agent can now:\n");
-    console.log("   • Query 1B+ LinkedIn profiles (orangeslice.b2b.sql)");
-    console.log("   • Search Google (orangeslice.serp.search)");
-    console.log("   • Scrape websites (orangeslice.firecrawl.scrape)\n");
+    console.log("   AGENTS.md at project root - Claude Code will auto-detect it.\n");
+    console.log("   Available tools:\n");
+    console.log("   • orangeslice.b2b.sql()           - 1B+ LinkedIn profiles");
+    console.log("   • orangeslice.serp.search()       - Google Search");
+    console.log("   • orangeslice.firecrawl.scrape()  - Static web scraping");
+    console.log("   • orangeslice.browser.execute()   - Playwright automation");
+    console.log("   • orangeslice.generateObject()    - AI structured output");
+    console.log("   • orangeslice.apify.run()         - Pre-built scrapers");
+    console.log("   • orangeslice.geo.parseAddress()  - Geocoding\n");
 }
 main().catch(console.error);

package/dist/generateObject.d.ts

@@ -0,0 +1,34 @@
+export interface GenerateObjectOptions {
+    /** The prompt describing what to generate */
+    prompt: string;
+    /** JSON schema defining the output structure */
+    schema: Record<string, unknown>;
+    /** Model to use (default: "gpt-4o-mini") */
+    model?: string;
+}
+/**
+ * Generate a structured object using AI
+ *
+ * @example
+ * const result = await generateObject.generate({
+ *   prompt: "Extract the company name and founding year from: Apple Inc was founded in 1976",
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       company: { type: "string" },
+ *       year: { type: "number" }
+ *     },
+ *     required: ["company", "year"]
+ *   }
+ * });
+ * // { company: "Apple Inc", year: 1976 }
+ */
+export declare function generate<T = Record<string, unknown>>(options: GenerateObjectOptions): Promise<T>;
+/**
+ * Convenience method for extracting data from text
+ */
+export declare function extract<T = Record<string, unknown>>(text: string, schema: Record<string, unknown>, instructions?: string): Promise<T>;
+export declare const generateObject: {
+    generate: typeof generate;
+    extract: typeof extract;
+};

package/dist/generateObject.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateObject = void 0;
+exports.generate = generate;
+exports.extract = extract;
+const queue_1 = require("./queue");
+const API_URL = process.env.ORANGESLICE_API_URL?.replace(/\?.*/, "") + "?functionId=generateObject"
+    || "https://orangeslice.ai/api/function?functionId=generateObject";
+// Rate limit: 2 concurrent, 200ms between requests
+const queue = (0, queue_1.createQueue)(2);
+const rateLimiter = (0, queue_1.createRateLimiter)(200);
+/**
+ * Helper to make POST request, handling redirects manually
+ */
+async function fetchWithRedirect(url, body) {
+    let response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        redirect: "manual",
+    });
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (location) {
+            response = await fetch(location, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+            });
+        }
+    }
+    return response;
+}
+/**
+ * Generate a structured object using AI
+ *
+ * @example
+ * const result = await generateObject.generate({
+ *   prompt: "Extract the company name and founding year from: Apple Inc was founded in 1976",
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       company: { type: "string" },
+ *       year: { type: "number" }
+ *     },
+ *     required: ["company", "year"]
+ *   }
+ * });
+ * // { company: "Apple Inc", year: 1976 }
+ */
+async function generate(options) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({
+                prompt: options.prompt,
+                schema: options.schema,
+                model: options.model,
+            });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`generateObject request failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (data.error) {
+                throw new Error(`generateObject error: ${data.error}`);
+            }
+            return data;
+        });
+    });
+}
+/**
+ * Convenience method for extracting data from text
+ */
+async function extract(text, schema, instructions) {
+    const prompt = instructions
+        ? `${instructions}\n\nText:\n${text}`
+        : `Extract structured data from the following text:\n\n${text}`;
+    return generate({ prompt, schema });
+}
+// Export as namespace
+exports.generateObject = {
+    generate,
+    extract,
+};

package/dist/geo.d.ts

@@ -0,0 +1,50 @@
+export interface ParsedAddress {
+    streetNumber: string;
+    route: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+    lat: number;
+    lng: number;
+}
+/**
+ * Parse an address string into structured components using Google Maps Geocoding
+ *
+ * @example
+ * const parsed = await geo.parseAddress("1600 Amphitheatre Parkway, Mountain View, CA");
+ * // {
+ * //   streetNumber: "1600",
+ * //   route: "Amphitheatre Parkway",
+ * //   city: "Mountain View",
+ * //   state: "California",
+ * //   postalCode: "94043",
+ * //   country: "United States",
+ * //   lat: 37.4224764,
+ * //   lng: -122.0842499
+ * // }
+ */
+export declare function parseAddress(address: string): Promise<ParsedAddress>;
+/**
+ * Get coordinates (lat/lng) for an address
+ *
+ * @example
+ * const coords = await geo.geocode("Times Square, NYC");
+ * // { lat: 40.758896, lng: -73.985130 }
+ */
+export declare function geocode(address: string): Promise<{
+    lat: number;
+    lng: number;
+}>;
+/**
+ * Get the city and state for an address
+ */
+export declare function getCityState(address: string): Promise<{
+    city: string;
+    state: string;
+}>;
+export declare const geo: {
+    parseAddress: typeof parseAddress;
+    geocode: typeof geocode;
+    getCityState: typeof getCityState;
+};

package/dist/geo.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geo = void 0;
+exports.parseAddress = parseAddress;
+exports.geocode = geocode;
+exports.getCityState = getCityState;
+const queue_1 = require("./queue");
+const API_URL = process.env.ORANGESLICE_API_URL?.replace(/\?.*/, "") + "?functionId=geo"
+    || "https://orangeslice.ai/api/function?functionId=geo";
+// Rate limit: 2 concurrent, 100ms between requests
+const queue = (0, queue_1.createQueue)(2);
+const rateLimiter = (0, queue_1.createRateLimiter)(100);
+/**
+ * Helper to make POST request, handling redirects manually
+ */
+async function fetchWithRedirect(url, body) {
+    let response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        redirect: "manual",
+    });
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (location) {
+            response = await fetch(location, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+            });
+        }
+    }
+    return response;
+}
+/**
+ * Parse an address string into structured components using Google Maps Geocoding
+ *
+ * @example
+ * const parsed = await geo.parseAddress("1600 Amphitheatre Parkway, Mountain View, CA");
+ * // {
+ * //   streetNumber: "1600",
+ * //   route: "Amphitheatre Parkway",
+ * //   city: "Mountain View",
+ * //   state: "California",
+ * //   postalCode: "94043",
+ * //   country: "United States",
+ * //   lat: 37.4224764,
+ * //   lng: -122.0842499
+ * // }
+ */
+async function parseAddress(address) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({ address });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Geo parseAddress failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (data.error) {
+                throw new Error(`Geo error: ${data.error}`);
+            }
+            return data;
+        });
+    });
+}
+/**
+ * Get coordinates (lat/lng) for an address
+ *
+ * @example
+ * const coords = await geo.geocode("Times Square, NYC");
+ * // { lat: 40.758896, lng: -73.985130 }
+ */
+async function geocode(address) {
+    const parsed = await parseAddress(address);
+    return { lat: parsed.lat, lng: parsed.lng };
+}
+/**
+ * Get the city and state for an address
+ */
+async function getCityState(address) {
+    const parsed = await parseAddress(address);
+    return { city: parsed.city, state: parsed.state };
+}
+// Export as namespace
+exports.geo = {
+    parseAddress,
+    geocode,
+    getCityState,
+};

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import { b2b } from "./b2b";
 import { serp } from "./serp";
 import { firecrawl } from "./firecrawl";
 import { browser } from "./browser";
-export { b2b, serp, firecrawl, browser };
+import { generateObject } from "./generateObject";
+import { apify } from "./apify";
+import { geo } from "./geo";
+export { b2b, serp, firecrawl, browser, generateObject, apify, geo };
 /**
  * Main orangeslice namespace - AI sales agent toolkit
  *
@@ -15,15 +18,27 @@ export { b2b, serp, firecrawl, browser };
  * // Google Search
  * const results = await orangeslice.serp.search("best CRM software 2024");
  *
- * // Website Scraping (simple)
+ * // Website Scraping (static pages)
  * const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
  *
- * // Browser Automation (Playwright)
+ * // Browser Automation (dynamic pages, Playwright)
  * const data = await orangeslice.browser.execute(`
  *   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
  *   return await page.evaluate(() => document.title);
  * `);
  *
+ * // AI Structured Output
+ * const extracted = await orangeslice.generateObject.generate({
+ *   prompt: "Extract company info from: Apple was founded in 1976",
+ *   schema: { type: "object", properties: { name: { type: "string" }, year: { type: "number" } } }
+ * });
+ *
+ * // Apify Actors (web scrapers)
+ * const reviews = await orangeslice.apify.run("compass/crawler-google-places", { searchStringsArray: ["cafes NYC"] });
+ *
+ * // Geocoding
+ * const location = await orangeslice.geo.parseAddress("1600 Amphitheatre Parkway, Mountain View, CA");
+ *
  * // All calls are automatically rate-limited and queued
  */
 export declare const orangeslice: {
@@ -46,5 +61,19 @@ export declare const orangeslice: {
         snapshot: typeof import("./browser").snapshot;
         text: typeof import("./browser").text;
     };
+    generateObject: {
+        generate: typeof import("./generateObject").generate;
+        extract: typeof import("./generateObject").extract;
+    };
+    apify: {
+        run: typeof import("./apify").run;
+        search: typeof import("./apify").search;
+        getInputSchema: typeof import("./apify").getInputSchema;
+    };
+    geo: {
+        parseAddress: typeof import("./geo").parseAddress;
+        geocode: typeof import("./geo").geocode;
+        getCityState: typeof import("./geo").getCityState;
+    };
 };
 export default orangeslice;