orangeslice 2.4.1-beta.0 → 2.5.0

package/dist/api.js

@@ -105,6 +105,14 @@ async function fetchWithRedirect(url, init) {
     }
     return res;
 }
+function formatRequestError(endpoint, status, message) {
+    // 4xx → caller-fixable problem: surface just the server's message so it reads
+    // like a normal validation error (e.g. `Cannot resolve sheet "leads"`).
+    // 5xx → infra-shaped problem: keep the noisy prefix so callers can grep logs.
+    if (status >= 400 && status < 500)
+        return message;
+    return `[orangeslice] ${endpoint}: ${status} ${message}`;
+}
 async function pollUntilComplete(baseUrl, endpoint, pending) {
     const pollUrl = resolvePollUrl(baseUrl, pending);
     const timeoutAt = Date.now() + POLL_TIMEOUT_MS;
@@ -122,11 +130,14 @@ async function pollUntilComplete(baseUrl, endpoint, pending) {
         }
         if (!res.ok) {
             const message = asErrorMessage(data) || JSON.stringify(data);
-            throw new Error(`[orangeslice] ${endpoint}: ${res.status} ${message}`);
+            throw new Error(formatRequestError(endpoint, res.status, message));
         }
         const message = asErrorMessage(data);
         if (message) {
-            throw new Error(`[orangeslice] ${endpoint}: ${message}`);
+            // 2xx body carrying an `error` field is semantically a caller-fixable
+            // error delivered asynchronously — treat it like a 4xx so the message
+            // surfaces cleanly without the `[orangeslice] /endpoint: …` prefix.
+            throw new Error(formatRequestError(endpoint, 400, message));
         }
         return data;
     }
@@ -153,7 +164,7 @@ async function post(endpoint, payload) {
     if (!res.ok) {
         const data = await readResponseBody(res);
         const message = asErrorMessage(data) || (typeof data === "string" ? data : JSON.stringify(data));
-        throw new Error(`[orangeslice] ${endpoint}: ${res.status} ${message}`);
+        throw new Error(formatRequestError(endpoint, res.status, message));
     }
     const data = await readResponseBody(res);
     if (isPendingResponse(data)) {

package/dist/ctx.d.ts

@@ -25,6 +25,20 @@ export interface SpreadsheetListItem {
     orgId: string | null;
     userId: string | null;
 }
+export interface SpreadsheetDescribeColumn {
+    id: string;
+    name: string;
+}
+export interface SpreadsheetDescribeSheet {
+    id: string;
+    name: string;
+    columns: SpreadsheetDescribeColumn[];
+}
+export interface SpreadsheetDescribeResult {
+    id: string;
+    name: string;
+    sheets: SpreadsheetDescribeSheet[];
+}
 export interface SqlQueryResult {
     rows: Record<string, unknown>[];
     rowIds: string[];
@@ -61,6 +75,7 @@ export declare const ctx: {
     sql: (spreadsheetId: string, sql: string) => Promise<SqlResult>;
     spreadsheet: (spreadsheetId: string) => {
         sql: (sql: string) => Promise<SqlResult>;
+        describe: () => Promise<SpreadsheetDescribeResult>;
         sheet: (sheetName: string) => {
             addRows: (rows: Record<string, unknown> | Record<string, unknown>[]) => Promise<RowsAddResult>;
         };

package/dist/ctx.js

@@ -44,6 +44,7 @@ function createSpreadsheetHandle(spreadsheetId) {
             assertNotRun(sql);
             return (0, api_1.post)("/ctx/sql", { spreadsheetId, sql });
         },
+        describe: () => (0, api_1.post)("/ctx/spreadsheet/describe", { spreadsheetId }),
         sheet: (sheetName) => createSheetHandle(spreadsheetId, sheetName)
     };
 }

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { Skill, SkillListParams, SkillCreateParams, SkillUpdateParams } fro
 export { findCareersPage, scrapeCareersPage } from "./careers";
 export type { FindCareersPageParams, FindCareersPageResult, ScrapeCareersPageParams, ScrapeCareersPageResult, ScrapeCareersPageJob } from "./careers";
 export { ctx } from "./ctx";
-export type { Spreadsheet, SpreadsheetListItem, SqlResult, SqlQueryResult, SqlActionResult, RowsAddResult } from "./ctx";
+export type { Spreadsheet, SpreadsheetListItem, SpreadsheetDescribeResult, SpreadsheetDescribeSheet, SpreadsheetDescribeColumn, SqlResult, SqlQueryResult, SqlActionResult, RowsAddResult } from "./ctx";
 export { linkedinSearch } from "./b2b";
 export type { LinkedInSearchParams, LinkedInSearchResponse } from "./b2b";
 export { crunchbaseSearch } from "./crunchbase";

package/docs/integrations/index.md

@@ -240,6 +240,34 @@ await integrations.attio.createNote({
 
 See [attio/](./attio/) for all available functions.
 
+### Website tracking
+
+LinkedIn-person identification for US-based website visitors. Customers
+paste a single `<script>` tag on their site; each identified visit lands
+as a row on the spreadsheet that owns the trigger.
+
+```typescript
+// Enroll a single domain — creates the trigger + sheet ingester, registers
+// the domain in our master webhook routing table, adds it to the upstream
+// allow-list, and returns the <script> the user pastes on their site.
+const { script } = await integrations.websiteTracking.setupTracking({
+   domain: "acme.com",
+   sheetName: "Website Visitors"
+});
+
+// Inspect / remove later
+const tracked = await integrations.websiteTracking.listTrackedDomains();
+await integrations.websiteTracking.removeTracking("acme.com");
+```
+
+Pricing: **80 credits per identified visitor** (charged at the master
+webhook). Repeat visits and company-only pings are forwarded to the sheet
+but don't cost credits. When the account runs out of credits the domain
+is automatically paused; the next top-up resumes it.
+
+See [websiteTracking/](./websiteTracking/) for the full recipe,
+canonical visitor shape, and trigger code template.
+
 ### Gmail
 
 Read and write emails from connected Google Gmail accounts.

package/docs/integrations/websiteTracking/index.md

@@ -0,0 +1,86 @@
+---
+name: integrations/websiteTracking
+description: Track website visitors (LinkedIn person identification). Use when a user asks to identify who is visiting their site, build website-intent lists, or trigger outreach from anonymous traffic.
+---
+
+# Website Visitor Identification
+
+Identify the LinkedIn profile of US-based visitors to a customer's
+website. The customer pastes a single `<script>` tag on their site;
+every identified visit lands as a row on the spreadsheet that owns the
+trigger.
+
+- **One shared tracking script** is pasted on the customer's site. No
+  per-customer external account, no logins, no separate billing.
+- Every visitor ping fans out to a **master webhook** we own. The
+  master webhook looks up the captured domain, charges the customer's
+  Orange Slice credit balance, then forwards the visitor record to a
+  trigger on the customer's spreadsheet which writes it as a row.
+
+## Pricing
+
+**80 credits per identified visitor.** A visitor counts as "identified"
+when we resolve both a LinkedIn URL and a first name on a non-repeat
+visit. Company-only pings and repeat visitor pings are recorded for
+context but NEVER charge credits.
+
+When the customer's balance hits zero, the master webhook automatically
+pauses their domain so they stop incurring charges. The next top-up
+resumes the domain automatically — the customer doesn't have to re-paste
+the script.
+
+## The Recipe (call once per domain)
+
+```typescript
+const { script, triggerId } = await integrations.websiteTracking.setupTracking({
+   domain: "acme.com",
+   sheetName: "Website Visitors" // optional, defaults to this
+});
+
+// Hand `script` to the user — they paste it on their site.
+```
+
+`setupTracking` does all of the following atomically:
+
+1. Creates a sheet-aware trigger that ingests visitor payloads into the
+   chosen sheet (uses `addRows` with `createMissingColumns: true` so the
+   user doesn't have to pre-create columns).
+2. Inserts the domain → trigger mapping into our master routing table.
+3. Calls the upstream allow-list API to register the domain.
+4. Returns the canonical `<script>` tag the user pastes on their site.
+
+If the same domain is re-enrolled it is idempotent — the existing
+trigger and mapping are reused.
+
+## After setupTracking — what to tell the user
+
+1. Paste the returned `script` into the `<head>` of their website.
+2. Let them know identified visitors will appear in the chosen sheet
+   within ~5 minutes of installing. Pricing: 80 credits per identified
+   person.
+3. If they want to enrich rows further, point out that the trigger only
+   ingests — they should add **column code** (or just let the AI suggest
+   columns) for tasks like "compute company size" or "draft an outreach
+   email" so per-row work shows in the UI and is retryable.
+
+## Multiple sites
+
+A single account can track many domains, each with its own trigger and
+sheet. Just call `setupTracking` once per domain. A domain can only be
+tracked by ONE Orange Slice account at a time — re-enrolling from another
+account throws unless the original account previously called
+`removeTracking` (then the row is a tombstone and the new account can
+claim it).
+
+## Inspecting / removing
+
+```typescript
+// What's tracked on this spreadsheet?
+const mappings = await integrations.websiteTracking.listTrackedDomains();
+
+// Stop tracking a domain.
+await integrations.websiteTracking.removeTracking("acme.com");
+```
+
+See [setupTracking.md](./setupTracking.md) for the full input/output
+contract.

package/docs/integrations/websiteTracking/setupTracking.md

@@ -0,0 +1,110 @@
+---
+name: integrations/websiteTracking/setupTracking
+description: Atomic enrollment helper — creates the receiving trigger, registers the domain in the master webhook table, adds the domain to the upstream allow-list, returns the user-facing <script> tag.
+---
+
+# integrations.websiteTracking.setupTracking
+
+Enroll one customer domain into website-visitor tracking.
+
+## Input
+
+```typescript
+{
+  domain: string;          // e.g. "acme.com" (with or without scheme/www)
+  sheetName?: string;      // defaults to "Website Visitors"
+  triggerName?: string;    // defaults to `Website visitors – {domain}`
+}
+```
+
+The `domain` is normalized: protocol, `www.`, paths, query, and ports are
+stripped before storage. `"https://www.acme.com/pricing"` and `"acme.com"`
+both store as `acme.com`.
+
+## Output
+
+```typescript
+{
+  script: string;              // <script> tag for the user to paste
+  domain: string;              // normalized domain
+  triggerId: string;
+  mappingId: string;
+  sheetName: string;
+  triggerName: string;
+  alreadyOwned: boolean;       // true if mapping existed before this call
+  alreadyOnAllowList: boolean; // true if the upstream allow-list already had the domain
+}
+```
+
+## Errors
+
+- `Invalid domain` — `domain` couldn't be normalized to a host with a TLD.
+- `Domain "<x>" is already claimed by another account` — every domain
+  belongs to exactly one Orange Slice account (a `removed` tombstone from
+  a prior teardown does NOT lock the domain).
+
+## What the trigger does
+
+The trigger code generated by this helper stays thin per the
+[triggers-runtime.md](../../triggers-runtime.md) rule: it just normalizes
+the upstream payload into the canonical visitor shape and pushes a row
+into the user's chosen sheet with `createMissingColumns: true` and
+`run: true`. Any enrichment / scoring belongs in column code on that
+sheet.
+
+## Canonical visitor shape
+
+Every identified visit is delivered to the trigger as a record with
+these fields:
+
+```typescript
+{
+  linkedinUrl: string | null;
+  firstName: string | null;
+  lastName: string | null;
+  title: string | null;
+  companyName: string | null;
+  businessEmail: string | null;
+  website: string | null;
+  industry: string | null;
+  employeeCount: number | string | null;
+  estimatedRevenue: string | null;
+  city: string | null;
+  state: string | null;
+  zip: string | null;
+  seenAt: string | null;
+  referrer: string | null;
+  capturedUrl: string | null;
+  tags: string | null;
+  isRepeatVisit: boolean;
+  extra?: Record<string, unknown>; // optional extras (UTMs, seniority, etc.)
+}
+```
+
+## Example chat flow
+
+When a user says "I want to track who visits my site", do this:
+
+```typescript
+const result = await integrations.websiteTracking.setupTracking({
+   domain: "acme.com"
+});
+
+// Then tell the user:
+//   1. Paste this snippet (`result.script`) into the <head> of acme.com.
+//   2. Identified visitors will land in the "Website Visitors" sheet.
+//   3. Each identified visitor costs 80 credits. Repeat / company-only
+//      visits are free.
+//   4. If credits run out, tracking pauses automatically and resumes on
+//      the next top-up.
+```
+
+## Pricing recap
+
+Charged once per ping where:
+- `linkedinUrl` is present, AND
+- `firstName` is present, AND
+- `isRepeatVisit` is not `true`.
+
+Cost: **80 credits**. Company-only and repeat visits are still forwarded
+to the sheet (so the user can analyze recurring traffic) but cost zero.

package/docs/services/ctx/index.md

@@ -53,8 +53,30 @@ await ss.sheet("contacts").addRows([
 ```
 
 - **`ss.sql(sql)`** — Execute EAV-SQL (same as `ctx.sql` but without needing to pass spreadsheetId).
+- **`ss.describe()`** — Return the structural snapshot of the spreadsheet: its `id`, `name`, and an array of `sheets`, each with its `columns`. Use this to discover sheet/column names before issuing SQL — especially when attaching to a spreadsheet you didn't create.
 - **`ss.sheet(name).addRows(rows)`** — Insert one or more rows into the named sheet. Accepts a single row object or an array. Missing columns are auto-created.
 
+### Attaching to an existing spreadsheet
+
+When the spreadsheet was created elsewhere (e.g. in the UI), use `describe()` to discover what's inside before running SQL:
+
+```typescript
+const { spreadsheets } = await ctx.listSpreadsheets();
+const target = spreadsheets.find((s) => s.name === "Find more paying customers V1")!;
+
+const ss = ctx.spreadsheet(target.id);
+const info = await ss.describe();
+// info.sheets: [{ id, name, columns: [{ id, name }] }, ...]
+
+for (const sheet of info.sheets) {
+   const cols = sheet.columns.map((c) => c.name).join(", ");
+   console.log(`${sheet.name}: ${cols}`);
+}
+
+// Now you know the real sheet names; query safely
+const result = await ss.sql(`SELECT * FROM "${info.sheets[0].name}" LIMIT 10`);
+```
+
 ## EAV-SQL Reference
 
 The `sql` method supports a subset of SQL mapped to Orange Slice's EAV storage:

package/package.json

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