orangeslice 2.1.3 → 2.1.4-beta.0

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/services/ctx/index.md

@@ -0,0 +1,68 @@
+---
+description: Spreadsheet management — create spreadsheets, run SQL, add rows
+---
+
+# ctx — Spreadsheet Context API
+
+Manage Orange Slice spreadsheets programmatically. Create spreadsheets, add sheets and columns via SQL, query data, insert rows.
+
+## Quick start
+
+```typescript
+import { ctx } from "orangeslice";
+
+// Create a spreadsheet
+const ss = await ctx.createSpreadsheet({ name: "Leads" });
+
+// Create a sheet with columns
+await ctx.sql(ss.id, "CREATE TABLE contacts (name, email, website)");
+
+// Insert data
+await ctx.sql(ss.id, "INSERT INTO contacts (name, email) VALUES ('Acme', 'hi@acme.com')");
+
+// Query data
+const result = await ctx.sql(ss.id, "SELECT * FROM contacts WHERE name = 'Acme'");
+console.log(result.rows);
+```
+
+## Methods
+
+### Top-level
+
+- **`ctx.createSpreadsheet({ name })`** — Create a new spreadsheet. The scope (personal vs org) is determined by the API key. Returns `{ id, name }`.
+- **`ctx.listSpreadsheets()`** — List spreadsheets visible to the API key's scope. Returns `{ spreadsheets: [...] }`.
+- **`ctx.deleteSpreadsheet(spreadsheetId)`** — Soft-delete a spreadsheet (must be within the API key's scope).
+- **`ctx.sql(spreadsheetId, sql)`** — Execute EAV-SQL against a spreadsheet within the API key's scope (see SQL reference below).
+
+### Bound spreadsheet
+
+Call `ctx.spreadsheet(id)` to get a handle bound to a specific spreadsheet:
+
+```typescript
+const ss = ctx.spreadsheet("uuid-here");
+await ss.sql("SELECT * FROM contacts");
+await ss.sheet("contacts").addRow({ name: "Corp", email: "corp@example.com" });
+await ss.sheet("contacts").addRows([
+   { name: "Foo", email: "foo@example.com" },
+   { name: "Bar", email: "bar@example.com" }
+]);
+```
+
+- **`ss.sql(sql)`** — Execute EAV-SQL (same as `ctx.sql` but without needing to pass spreadsheetId).
+- **`ss.sheet(name).addRow(row)`** — Insert a single row into the named sheet.
+- **`ss.sheet(name).addRows(rows)`** — Insert multiple rows.
+
+## EAV-SQL Reference
+
+The `sql` method supports a subset of SQL mapped to Orange Slice's EAV storage:
+
+| Statement      | Example                                                    | Description                      |
+| -------------- | ---------------------------------------------------------- | -------------------------------- |
+| `CREATE TABLE` | `CREATE TABLE leads (name, email, website)`                | Creates a new sheet with columns |
+| `SELECT`       | `SELECT name, email FROM leads WHERE email LIKE '%@acme%'` | Query rows                       |
+| `INSERT INTO`  | `INSERT INTO leads (name) VALUES ('Acme')`                 | Add rows                         |
+| `ALTER TABLE`  | `ALTER TABLE leads ADD COLUMN phone`                       | Add/rename/drop columns          |
+| `DELETE FROM`  | `DELETE FROM leads WHERE email IS NULL`                    | Delete rows                      |
+| `DROP TABLE`   | `DROP TABLE leads`                                         | Delete a sheet                   |
+
+> **Note:** `RUN` commands are not supported via the API.

package/docs/services/index.md

@@ -1,3 +1,4 @@
+- **ctx**: Spreadsheet management — create spreadsheets, run SQL, add sheets/columns/rows programmatically.
 - **ai**: AI helpers (summaries, classifications, scoring).
 - **apify**: Run any of 10,000+ Apify actors for web scraping, social media, e-commerce, and more.
 - **browser**: Kernel browser automation - spin up cloud browsers, execute Playwright code, take screenshots. **Use this for scraping structured lists of repeated data** (e.g., product listings, search results, table rows) where you know the DOM structure. Also ideal for **intercepting network requests** to discover underlying APIs, then paginate those APIs directly in your code (faster & cheaper than clicking through pages). Perfect for JS-heavy sites that don't work with simple HTTP scraping.

package/package.json

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