orangeslice 2.1.2 → 2.1.3

package/README.md

@@ -6,13 +6,16 @@ Orangeslice provides a `services.*` API for B2B research, enrichment, scraping,
 
 ```bash
 npx orangeslice
+bunx orangeslice
+pnpm dlx orangeslice
+yarn dlx orangeslice
 ```
 
 The CLI copies docs to `./orangeslice-docs`, creates `./orangeslice-docs/AGENTS.md`, initializes `package.json` when missing, installs `orangeslice` in the current directory, opens browser auth, and stores your API key in `~/.config/orangeslice/config.json`.
 
 ### Auth behavior
 
-- `npx orangeslice` uses browser-based device auth and auto-provisions an API key.
+- Any supported runner (`npx`, `bunx`, `pnpm dlx`, `yarn dlx`) uses browser-based device auth and auto-provisions an API key.
 - SDK credential precedence:
    1. `configure({ apiKey })`
    2. `ORANGESLICE_API_KEY` env var
@@ -21,23 +24,32 @@ The CLI copies docs to `./orangeslice-docs`, creates `./orangeslice-docs/AGENTS.
 ### CLI auth commands
 
 ```bash
-# One-time setup (also runs on plain `npx orangeslice` when unauthenticated)
+# One-time setup (also runs on plain `npx orangeslice` / `bunx orangeslice` when unauthenticated)
 npx orangeslice login
+bunx orangeslice login
+pnpm dlx orangeslice login
+yarn dlx orangeslice login
 
 # Force re-auth and replace local stored key
 npx orangeslice login --force
+bunx orangeslice login --force
 
 # Remove locally stored key
 npx orangeslice logout
+bunx orangeslice logout
 
 # Show current auth source (env or config file)
 npx orangeslice auth status
+bunx orangeslice auth status
 ```
 
 Install as a dependency when writing app code:
 
 ```bash
 npm install orangeslice
+bun add orangeslice
+pnpm add orangeslice
+yarn add orangeslice
 ```
 
 ## Public API (services-first)
@@ -101,7 +113,7 @@ All service calls go through `post()` in `src/api.ts`.
 
 ## Docs installed by CLI
 
-After `npx orangeslice`, you should have:
+After running the CLI bootstrap command, you should have:
 
 ```text
 orangeslice-docs/

package/dist/api.js

@@ -137,7 +137,7 @@ async function post(endpoint, payload) {
     const apiKey = resolveApiKey();
     if (!apiKey) {
         throw new Error("[orangeslice] No API key configured. " +
-            "Run `npx orangeslice`, set ORANGESLICE_API_KEY in your environment, or call configure({ apiKey: 'osk_...' }).");
+            "Run `npx orangeslice`, `bunx orangeslice`, `pnpm dlx orangeslice`, or `yarn dlx orangeslice`, set ORANGESLICE_API_KEY in your environment, or call configure({ apiKey: 'osk_...' }).");
     }
     const url = `${baseUrl}${endpoint}`;
     const body = JSON.stringify({ ...payload, inlineWaitMs: DEFAULT_INLINE_WAIT_MS });

package/dist/cli.js

@@ -47,6 +47,7 @@ const CONFIG_DIR = path.join(os.homedir(), ".config", "orangeslice");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const AGENTS_IMPORT_LINE = "@orangeslice-docs/AGENTS.md";
 const CLAUDE_IMPORT_LINE = "@orangeslice-docs/CLAUDE.md";
+const SUPPORTED_RUNNERS = ["npm", "bun", "pnpm", "yarn"];
 function isDir(p) {
     try {
         return fs.statSync(p).isDirectory();
@@ -71,6 +72,71 @@ function resolveDocsDir() {
     }
     return LEGACY_DOCS_DIR;
 }
+function hasFile(cwd, fileName) {
+    return fs.existsSync(path.join(cwd, fileName));
+}
+function readPackageManagerFromPackageJson(cwd) {
+    const packageJsonPath = path.join(cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const packageManager = parsed.packageManager?.toLowerCase() || "";
+        if (packageManager.startsWith("bun@"))
+            return "bun";
+        if (packageManager.startsWith("pnpm@"))
+            return "pnpm";
+        if (packageManager.startsWith("yarn@"))
+            return "yarn";
+        if (packageManager.startsWith("npm@"))
+            return "npm";
+    }
+    catch { }
+    return null;
+}
+function detectPackageManager(cwd) {
+    const fromPackageJson = readPackageManagerFromPackageJson(cwd);
+    if (fromPackageJson)
+        return fromPackageJson;
+    if (hasFile(cwd, "bun.lock") || hasFile(cwd, "bun.lockb"))
+        return "bun";
+    if (hasFile(cwd, "pnpm-lock.yaml"))
+        return "pnpm";
+    if (hasFile(cwd, "yarn.lock"))
+        return "yarn";
+    if (hasFile(cwd, "package-lock.json") || hasFile(cwd, "npm-shrinkwrap.json"))
+        return "npm";
+    const userAgent = process.env.npm_config_user_agent?.toLowerCase() || "";
+    if (userAgent.includes("bun/"))
+        return "bun";
+    if (userAgent.includes("pnpm/"))
+        return "pnpm";
+    if (userAgent.includes("yarn/"))
+        return "yarn";
+    return "npm";
+}
+function getRunnerCommand(packageManager, suffix = "") {
+    const command = packageManager === "bun"
+        ? "bunx orangeslice"
+        : packageManager === "pnpm"
+            ? "pnpm dlx orangeslice"
+            : packageManager === "yarn"
+                ? "yarn dlx orangeslice"
+                : "npx orangeslice";
+    return suffix ? `${command} ${suffix}` : command;
+}
+function getInstallCommand(packageManager) {
+    if (packageManager === "bun")
+        return "bun add orangeslice";
+    if (packageManager === "pnpm")
+        return "pnpm add orangeslice";
+    if (packageManager === "yarn")
+        return "yarn add orangeslice";
+    return "npm install orangeslice";
+}
+function getSupportedRunnerExamples() {
+    return SUPPORTED_RUNNERS.map((packageManager) => getRunnerCommand(packageManager));
+}
 function copyDirSync(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -105,7 +171,7 @@ Use these docs as the source of truth. If there is any conflict between your pri
   - \`import { services } from "orangeslice"\`
   - \`import { configure, services } from "orangeslice"\` when setting API key programmatically
 - Do NOT use \`import { services } from "./orangeslice"\` unless the user explicitly has a local wrapper file at that path.
-- \`npx orangeslice\` is a setup/bootstrap command (docs sync, package install, auth). It does NOT execute user app scripts.
+- The orangeslice bootstrap commands (\`npx orangeslice\`, \`bunx orangeslice\`, \`pnpm dlx orangeslice\`, \`yarn dlx orangeslice\`) sync docs, install the package, and handle auth. They do NOT execute user app scripts.
 
 ## Runtime Requirements
 - If writing standalone scripts that use top-level \`await\`, use ESM:
@@ -194,12 +260,21 @@ function ensurePackageJson(cwd) {
     const packageJsonPath = path.join(cwd, "package.json");
     if (fs.existsSync(packageJsonPath))
         return;
-    console.log("  No package.json found. Initializing npm project...");
-    (0, child_process_1.execSync)("npm init -y", { stdio: "inherit", cwd });
+    console.log("  No package.json found. Creating one...");
+    const defaultName = path
+        .basename(cwd)
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "orangeslice-app";
+    fs.writeFileSync(packageJsonPath, JSON.stringify({
+        name: defaultName,
+        version: "1.0.0",
+        private: true
+    }, null, 2) + "\n", "utf8");
 }
-function installOrangeslice(cwd) {
-    console.log("  Installing orangeslice...");
-    (0, child_process_1.execSync)("npm install orangeslice", { stdio: "inherit", cwd });
+function installOrangeslice(cwd, packageManager) {
+    console.log(`  Installing orangeslice with ${packageManager}...`);
+    (0, child_process_1.execSync)(getInstallCommand(packageManager), { stdio: "inherit", cwd });
 }
 function readConfigFile() {
     try {
@@ -312,13 +387,17 @@ async function setupApiKey(force = false) {
     saveConfigFile({ apiKey });
     console.log(`  ✓ API key saved to ${CONFIG_PATH}\n`);
 }
-function printHelp() {
+function printHelp(packageManager) {
     console.log("Usage:");
-    console.log("  npx orangeslice");
-    console.log("  npx orangeslice login [--force]");
-    console.log("  npx orangeslice logout");
-    console.log("  npx orangeslice auth <API_KEY>");
-    console.log("  npx orangeslice auth status\n");
+    for (const command of getSupportedRunnerExamples()) {
+        console.log(`  ${command}`);
+    }
+    console.log("");
+    console.log("Commands:");
+    console.log(`  ${getRunnerCommand(packageManager, "login [--force]")}`);
+    console.log(`  ${getRunnerCommand(packageManager, "logout")}`);
+    console.log(`  ${getRunnerCommand(packageManager, "auth <API_KEY>")}`);
+    console.log(`  ${getRunnerCommand(packageManager, "auth status")}\n`);
 }
 async function runLogin(args) {
     const force = args.includes("--force");
@@ -336,16 +415,16 @@ function runLogout() {
         console.log("  Note: ORANGESLICE_API_KEY env var is still set in this shell.");
     }
 }
-function runAuthSet(apiKey) {
+function runAuthSet(apiKey, packageManager) {
     const trimmed = apiKey.trim();
     if (!trimmed) {
-        console.log("  Usage: npx orangeslice auth <API_KEY>");
+        console.log(`  Usage: ${getRunnerCommand(packageManager, "auth <API_KEY>")}`);
         return;
     }
     saveConfigFile({ apiKey: trimmed });
     console.log(`  ✓ API key saved to ${CONFIG_PATH} (${maskKey(trimmed)})`);
 }
-function runAuthStatus() {
+function runAuthStatus(packageManager) {
     const envKey = process.env.ORANGESLICE_API_KEY?.trim() || "";
     if (envKey) {
         console.log(`  Authenticated via env var: ${maskKey(envKey)}`);
@@ -356,11 +435,13 @@ function runAuthStatus() {
         console.log(`  Authenticated via config file (${CONFIG_PATH}): ${maskKey(fileKey)}`);
         return;
     }
-    console.log("  Not authenticated. Run `npx orangeslice login`.");
+    console.log(`  Not authenticated. Run \`${getRunnerCommand(packageManager, "login")}\`.`);
 }
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
+    const cwd = process.cwd();
+    const packageManager = detectPackageManager(cwd);
     if (command === "login") {
         await runLogin(args.slice(1));
         return;
@@ -372,18 +453,18 @@ async function main() {
     if (command === "auth") {
         const subcommand = args[1];
         if (subcommand === "status") {
-            runAuthStatus();
+            runAuthStatus(packageManager);
             return;
         }
         if (subcommand && subcommand !== "--help" && subcommand !== "-h") {
-            runAuthSet(subcommand);
+            runAuthSet(subcommand, packageManager);
             return;
         }
-        printHelp();
+        printHelp(packageManager);
         return;
     }
     if (command && (command === "--help" || command === "-h" || command === "help")) {
-        printHelp();
+        printHelp(packageManager);
         return;
     }
     console.log("\norangeslice\n");
@@ -396,11 +477,10 @@ async function main() {
     writeClaudeGuide(TARGET_DIR);
     console.log(`  ✓ Docs (${path.basename(docsDir)}) → ./orangeslice-docs/\n`);
     // Always set up package installation in the current directory.
-    const cwd = process.cwd();
     ensureAgentsImport(cwd);
     ensureClaudeImport(cwd);
     ensurePackageJson(cwd);
-    installOrangeslice(cwd);
+    installOrangeslice(cwd, packageManager);
     console.log("  ✓ Package installed in current directory\n");
     // API key setup
     await setupApiKey();

package/docs/integrations/hubspot/getList.md

@@ -0,0 +1,52 @@
+# getList
+
+Get a specific HubSpot list by ID.
+
+```typescript
+// Fetch a list by ID
+const list = await integrations.hubspot.getList("123456");
+
+// Include the filter definition in the response
+const detailedList = await integrations.hubspot.getList("123456", {
+   includeFilters: true
+});
+
+console.log(list.name); // "Target Accounts"
+console.log(list.processingType); // "DYNAMIC"
+```
+
+## Input
+
+| Parameter                | Type      | Description                                                           |
+| ------------------------ | --------- | --------------------------------------------------------------------- |
+| `listId`                 | `string`  | The HubSpot list ID to retrieve                                       |
+| `options.includeFilters` | `boolean` | Include the list's filter definition in the response (default: false) |
+
+## Output
+
+```typescript
+{
+  listId: string;
+  listVersion: number;
+  name: string;
+  objectTypeId: string;
+  processingStatus: string;
+  processingType: string;
+  createdAt?: string;
+  updatedAt?: string;
+  deletedAt?: string;
+  createdById?: string;
+  updatedById?: string;
+  filtersUpdatedAt?: string;
+  size?: number;
+  membershipSettings?: Record<string, unknown>;
+  listPermissions?: Record<string, unknown>;
+  filterBranch?: Record<string, unknown>;
+}
+```
+
+## Notes
+
+- Set `includeFilters: true` when you need the list's filter definition
+- `objectTypeId` identifies the CRM object type the list contains, such as contacts or companies
+- `processingType` commonly indicates whether the list is dynamic, manual, or snapshot-based

package/docs/integrations/hubspot/index.md

@@ -1,5 +1,5 @@
 ---
-description: HubSpot CRM - contacts, companies, deals, workflows
+description: HubSpot CRM - contacts, companies, deals, lists, workflows
 ---
 
 # HubSpot Integration
@@ -41,6 +41,10 @@ Typed functions for HubSpot CRM operations.
 - `integrations.hubspot.updateFlow(flowId, input)` - Update an existing workflow
 - `integrations.hubspot.deleteFlow(flowId)` - Delete a workflow
 
+## Lists
+
+- `integrations.hubspot.getList(listId, options?)` - Get list by ID
+
 ## Properties
 
 - `integrations.hubspot.listProperties(objectType, options?)` - List all property definitions for an object type

package/docs/lookalike-search/index.md

@@ -0,0 +1,154 @@
+---
+name: lookalike-search
+description: Find companies and people similar to a user's best customers or seed list using Ocean.io. Mandatory read for any "find me companies like X" or "lookalike" request.
+---
+
+# Mode: Lookalike Search
+
+**Goal:** Find companies and people that are similar to a user's existing customers, seed domains, or ideal customer profile — using Ocean.io's lookalike engine.
+
+---
+
+## When to Use Lookalike Search
+
+Use Ocean.io lookalike search when the user:
+
+- Has **example companies** (domains) and wants to find more like them
+- Says "companies like", "similar to", "lookalike", "companies that look like my customers"
+- Wants to **expand a seed list** of known-good accounts into a larger pipeline
+- Needs **account-based prospecting** starting from a handful of reference accounts
+- Wants to find the **right people** at companies matching a lookalike profile
+
+**Not a good fit when:**
+
+- User wants keyword/niche discovery ("AI CRM companies") → use `web.search`
+- User wants funding-based filtering → use `crunchbase.search`
+- User wants a specific company lookup → use LinkedIn B2B DB
+- User only has descriptions, not example domains → use `web.search` or `crunchbase.search` first to build a seed list
+
+---
+
+## The Two Endpoints
+
+### 1. `services.ocean.search.companies` — Find Lookalike Companies
+
+Provide seed domains and filters, get back similar companies with rich firmographic data.
+
+```ts
+const results = await services.ocean.search.companies({
+   companiesFilters: {
+      lookalikeDomains: ["stripe.com", "brex.com", "ramp.com"],
+      companySizes: ["51-200", "201-500"],
+      countries: ["us"]
+   },
+   size: 50
+});
+
+// results.companies → array of { company, relevance }
+// results.total → total matches
+// results.searchAfter → cursor for next page
+```
+
+**Key filters:**
+
+| Filter             | Example                          | Notes                                            |
+| ------------------ | -------------------------------- | ------------------------------------------------ |
+| `lookalikeDomains` | `["stripe.com", "plaid.com"]`    | Core input — seed domains to find lookalikes for |
+| `companySizes`     | `["51-200", "201-500"]`          | Filter by employee count range                   |
+| `countries`        | `["us", "gb", "de"]`             | Two-letter ISO country codes                     |
+| `industries`       | `["SaaS", "Fintech"]`            | Industry category names                          |
+| `technologies`     | `["React", "Salesforce"]`        | Filter by tech stack                             |
+| `revenueRanges`    | `["1M-10M", "10M-50M"]`          | Revenue band filter                              |
+| `keywords`         | `["payments", "infrastructure"]` | Keyword filter                                   |
+| `ecommerce`        | `true`                           | E-commerce companies only                        |
+| `minScore`         | `0.5`                            | Minimum similarity score (0–1)                   |
+
+**Pagination:** Use `searchAfter` from the previous response for efficient cursor-based pagination. Max `size` per request is 100.
+
+### 2. `services.ocean.search.people` — Find People at Companies
+
+Combine company filters with people filters to find the right contacts.
+
+```ts
+const results = await services.ocean.search.people({
+   companiesFilters: {
+      lookalikeDomains: ["stripe.com", "brex.com"]
+   },
+   peopleFilters: {
+      seniorities: ["C-Level", "VP"],
+      departments: ["Engineering", "Product"]
+   },
+   size: 50,
+   enableEmailSearch: true
+});
+
+// results.people → array of OceanPersonResult
+// Each person has: name, jobTitle, linkedinUrl, email, phone, company info
+```
+
+**People filters:**
+
+| Filter               | Example                          | Notes                                            |
+| -------------------- | -------------------------------- | ------------------------------------------------ |
+| `seniorities`        | `["C-Level", "VP", "Director"]`  | Job seniority levels                             |
+| `departments`        | `["Engineering", "Sales"]`       | Department targeting                             |
+| `jobTitleKeywords`   | `["CTO", "Head of Engineering"]` | Title keyword matching                           |
+| `countries`          | `["us"]`                         | People location filter                           |
+| `lookalikePeopleIds` | `["id1", "id2"]`                 | Find people similar to these Ocean.io person IDs |
+
+**Contact data:**
+
+- Set `enableEmailSearch: true` to get verified email addresses
+- Set `enablePhoneSearch: true` to get verified phone numbers
+- Both cost additional Ocean.io credits
+
+---
+
+## Standard Workflow
+
+### Company-first (most common)
+
+1. **Collect seed domains** — from user input, an existing sheet column, or a prior prospecting step
+2. **Search lookalike companies** — `services.ocean.search.companies` with seed domains + filters
+3. **Add to sheet** — populate a "Companies" sheet with domain, name, size, industry, etc.
+4. **Qualify** — add enrichment columns (LinkedIn enrich, tech stack, etc.) to score/filter
+5. **Find people** — add a column using `services.ocean.search.people` or `services.company.getEmployeesFromLinkedin`
+
+### People-direct (when you already know the company profile)
+
+1. **Search people directly** — `services.ocean.search.people` with company + people filters
+2. **Add to sheet** — populate with name, title, email, LinkedIn URL, company
+3. **Qualify** — add verification/enrichment columns
+
+---
+
+## Pagination Pattern
+
+Ocean.io returns up to `size` results per call (max 100). For larger result sets, paginate with `searchAfter`:
+
+```ts
+let allCompanies = [];
+let searchAfter = undefined;
+
+for (let page = 0; page < 5; page++) {
+   const results = await services.ocean.search.companies({
+      companiesFilters: { lookalikeDomains: ["stripe.com"] },
+      size: 100,
+      searchAfter
+   });
+
+   allCompanies.push(...results.companies);
+   searchAfter = results.searchAfter;
+
+   if (!searchAfter || allCompanies.length >= results.total) break;
+}
+```
+
+---
+
+## Tips
+
+- **More seed domains = better results.** 3-5 seeds produce much better lookalikes than a single domain.
+- **Combine with enrichment.** Ocean.io returns firmographic data, but you can enrich further with LinkedIn, BuiltWith, or PredictLeads.
+- **Use `minScore`** to control result quality — higher = more similar but fewer results.
+- **Credits:** 5 credits per result. A search returning 50 companies = 250 credits. Reserve is based on the requested `size`.