orangeslice 2.1.2 → 2.1.4-beta.0

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/dist/ctx.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Spreadsheet context API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { ctx } from "orangeslice";
+ *
+ *   const ss = await ctx.createSpreadsheet({ name: "Leads" });
+ *   await ctx.sql(ss.id, 'CREATE TABLE contacts (name, email, website)');
+ *   await ctx.sql(ss.id, "INSERT INTO contacts (name, email) VALUES ('Acme', 'hi@acme.com')");
+ *   const { rows } = await ctx.sql(ss.id, "SELECT * FROM contacts");
+ *
+ *   // Or bind to a spreadsheet for convenience:
+ *   const bound = ctx.spreadsheet(ss.id);
+ *   await bound.sql("SELECT * FROM contacts WHERE name = 'Acme'");
+ *   await bound.sheet("contacts").addRow({ name: "Corp", email: "corp@example.com" });
+ */
+export interface Spreadsheet {
+    id: string;
+    name: string;
+}
+export interface SpreadsheetListItem {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    orgId: string | null;
+    userId: string | null;
+}
+export interface SqlQueryResult {
+    rows: Record<string, unknown>[];
+    rowIds: string[];
+    count?: number;
+    sql?: string;
+}
+export interface SqlActionResult {
+    success: boolean;
+    id?: string;
+    columns?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export type SqlResult = SqlQueryResult | SqlActionResult;
+export declare const ctx: {
+    createSpreadsheet: (opts: {
+        name: string;
+    }) => Promise<Spreadsheet>;
+    listSpreadsheets: () => Promise<{
+        spreadsheets: SpreadsheetListItem[];
+    }>;
+    deleteSpreadsheet: (spreadsheetId: string) => Promise<{
+        success: boolean;
+    }>;
+    sql: (spreadsheetId: string, sql: string) => Promise<SqlResult>;
+    spreadsheet: (spreadsheetId: string) => {
+        sql: (sql: string) => Promise<SqlResult>;
+        sheet: (sheetName: string) => {
+            addRow: (row: Record<string, unknown>) => Promise<SqlResult>;
+            addRows: (rows: Record<string, unknown>[]) => Promise<SqlResult>;
+        };
+    };
+};

package/dist/ctx.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Spreadsheet context API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { ctx } from "orangeslice";
+ *
+ *   const ss = await ctx.createSpreadsheet({ name: "Leads" });
+ *   await ctx.sql(ss.id, 'CREATE TABLE contacts (name, email, website)');
+ *   await ctx.sql(ss.id, "INSERT INTO contacts (name, email) VALUES ('Acme', 'hi@acme.com')");
+ *   const { rows } = await ctx.sql(ss.id, "SELECT * FROM contacts");
+ *
+ *   // Or bind to a spreadsheet for convenience:
+ *   const bound = ctx.spreadsheet(ss.id);
+ *   await bound.sql("SELECT * FROM contacts WHERE name = 'Acme'");
+ *   await bound.sheet("contacts").addRow({ name: "Corp", email: "corp@example.com" });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ctx = void 0;
+const api_1 = require("./api");
+// ---------------------------------------------------------------------------
+// SQL builder helpers
+// ---------------------------------------------------------------------------
+function escapeValue(val) {
+    if (val === null || val === undefined)
+        return "NULL";
+    if (typeof val === "number") {
+        if (!Number.isFinite(val))
+            throw new Error(`[orangeslice] Cannot use ${val} as a SQL value`);
+        return String(val);
+    }
+    if (typeof val === "boolean")
+        return String(val);
+    const str = String(val).replace(/'/g, "''");
+    return `'${str}'`;
+}
+function escapeName(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+function buildInsertSQL(sheetName, rows) {
+    if (rows.length === 0)
+        throw new Error("[orangeslice] addRows requires at least one row");
+    const allKeys = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row))
+            allKeys.add(key);
+    }
+    const columns = Array.from(allKeys);
+    const colList = columns.map(escapeName).join(", ");
+    const valueClauses = rows.map((row) => {
+        const vals = columns.map((col) => escapeValue(row[col]));
+        return `(${vals.join(", ")})`;
+    });
+    return `INSERT INTO ${escapeName(sheetName)} (${colList}) VALUES ${valueClauses.join(", ")}`;
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+function assertNotRun(sql) {
+    const trimmed = sql.trim().toUpperCase();
+    if (trimmed.startsWith("RUN ") || trimmed === "RUN") {
+        throw new Error("[orangeslice] RUN commands are not supported via the API");
+    }
+}
+// ---------------------------------------------------------------------------
+// Bound spreadsheet handle
+// ---------------------------------------------------------------------------
+function createSheetHandle(spreadsheetId, sheetName) {
+    return {
+        addRow: (row) => (0, api_1.post)("/ctx/sql", {
+            spreadsheetId,
+            sql: buildInsertSQL(sheetName, [row])
+        }),
+        addRows: (rows) => (0, api_1.post)("/ctx/sql", {
+            spreadsheetId,
+            sql: buildInsertSQL(sheetName, rows)
+        })
+    };
+}
+function createSpreadsheetHandle(spreadsheetId) {
+    return {
+        sql: (sql) => {
+            assertNotRun(sql);
+            return (0, api_1.post)("/ctx/sql", { spreadsheetId, sql });
+        },
+        sheet: (sheetName) => createSheetHandle(spreadsheetId, sheetName)
+    };
+}
+// ---------------------------------------------------------------------------
+// Top-level ctx object
+// ---------------------------------------------------------------------------
+exports.ctx = {
+    createSpreadsheet: (opts) => (0, api_1.post)("/ctx/spreadsheet/create", opts),
+    listSpreadsheets: () => (0, api_1.post)("/ctx/spreadsheet/list", {}),
+    deleteSpreadsheet: (spreadsheetId) => (0, api_1.post)("/ctx/spreadsheet/delete", { spreadsheetId }),
+    sql: (spreadsheetId, sql) => {
+        assertNotRun(sql);
+        return (0, api_1.post)("/ctx/sql", { spreadsheetId, sql });
+    },
+    spreadsheet: (spreadsheetId) => createSpreadsheetHandle(spreadsheetId)
+};

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { configure } from "./api";
 export type { OrangesliceConfig } from "./api";
+export { ctx } from "./ctx";
+export type { Spreadsheet, SpreadsheetListItem, SqlResult, SqlQueryResult, SqlActionResult } from "./ctx";
 export { linkedinSearch } from "./b2b";
 export type { LinkedInSearchParams, LinkedInSearchResponse } from "./b2b";
 export { crunchbaseSearch } from "./crunchbase";

package/dist/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.crunchbaseSearch = exports.linkedinSearch = exports.configure = void 0;
+exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.configure = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return api_1.configure; } });
+var ctx_1 = require("./ctx");
+Object.defineProperty(exports, "ctx", { enumerable: true, get: function () { return ctx_1.ctx; } });
 var b2b_1 = require("./b2b");
 Object.defineProperty(exports, "linkedinSearch", { enumerable: true, get: function () { return b2b_1.linkedinSearch; } });
 var crunchbase_1 = require("./crunchbase");

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