orangeslice 2.4.1 → 2.6.0

package/dist/api.d.ts

@@ -3,4 +3,13 @@ export interface OrangesliceConfig {
     baseUrl?: string;
 }
 export declare function configure(opts: OrangesliceConfig): void;
+/**
+ * Run `fn` with a per-call apiKey scoped via AsyncLocalStorage. Inside `fn`,
+ * `resolveApiKey()` returns this apiKey instead of falling back to the module
+ * singleton/env/config-file. Useful for server-side consumers (like the MCP
+ * route) that handle multiple users concurrently within one process.
+ *
+ * No-op on non-Node runtimes (falls back to the standard resolution chain).
+ */
+export declare function withApiKey<T>(apiKey: string, fn: () => T | Promise<T>): Promise<T>;
 export declare function post<T>(endpoint: string, payload: Record<string, unknown>): Promise<T>;

package/dist/api.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configure = configure;
+exports.withApiKey = withApiKey;
 exports.post = post;
 /**
  * Transport layer for orangeslice SDK.
@@ -14,16 +15,58 @@ const DEFAULT_INLINE_WAIT_MS = 5000;
 const USER_CONFIG_PATH = ".config/orangeslice/config.json";
 const _config = {};
 function configure(opts) {
-    if (opts.apiKey !== undefined)
-        _config.apiKey = opts.apiKey;
-    if (opts.baseUrl !== undefined)
-        _config.baseUrl = opts.baseUrl;
+    if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+        throw new Error("[orangeslice] configure() expects an object, e.g. configure({ apiKey: 'osk_...' })");
+    }
+    _config.apiKey = opts.apiKey;
+    _config.baseUrl = opts.baseUrl;
+}
+// AsyncLocalStorage is Node-only. Browser-style runtimes get a no-op shim so
+// that `withApiKey` doesn't crash; calls outside Node fall back to the
+// existing singleton/env/file resolution chain.
+let _callContextStore = null;
+function getCallContextStore() {
+    if (_callContextStore)
+        return _callContextStore;
+    if (!process?.versions?.node) {
+        _callContextStore = {
+            getStore: () => undefined,
+            run: (_ctx, fn) => fn()
+        };
+        return _callContextStore;
+    }
+    try {
+        const { AsyncLocalStorage } = require("node:async_hooks");
+        _callContextStore = new AsyncLocalStorage();
+        return _callContextStore;
+    }
+    catch {
+        _callContextStore = {
+            getStore: () => undefined,
+            run: (_ctx, fn) => fn()
+        };
+        return _callContextStore;
+    }
+}
+/**
+ * Run `fn` with a per-call apiKey scoped via AsyncLocalStorage. Inside `fn`,
+ * `resolveApiKey()` returns this apiKey instead of falling back to the module
+ * singleton/env/config-file. Useful for server-side consumers (like the MCP
+ * route) that handle multiple users concurrently within one process.
+ *
+ * No-op on non-Node runtimes (falls back to the standard resolution chain).
+ */
+function withApiKey(apiKey, fn) {
+    const store = getCallContextStore();
+    return Promise.resolve().then(() => store.run({ apiKey }, fn));
 }
 function resolveBaseUrl() {
-    return (_config.baseUrl || process.env.ORANGESLICE_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const ctx = getCallContextStore().getStore();
+    return (ctx?.baseUrl || _config.baseUrl || process.env.ORANGESLICE_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
 }
 function resolveApiKey() {
-    return _config.apiKey || process.env.ORANGESLICE_API_KEY || readApiKeyFromConfigFile() || "";
+    const ctx = getCallContextStore().getStore();
+    return ctx?.apiKey || _config.apiKey || process.env.ORANGESLICE_API_KEY || readApiKeyFromConfigFile() || "";
 }
 function readApiKeyFromConfigFile() {
     // Guard for browser-like runtimes.
@@ -95,16 +138,50 @@ function resolvePollUrl(baseUrl, pending) {
     }
     return `${baseUrl}/function/result/${pending.requestId}`;
 }
+function sameOrigin(a, b) {
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        return ua.protocol === ub.protocol && ua.host === ub.host;
+    }
+    catch {
+        // If either URL is unparseable, treat as cross-origin (fail closed).
+        return false;
+    }
+}
 async function fetchWithRedirect(url, init) {
     let res = await fetch(url, { ...init, redirect: "manual" });
     if (res.status >= 300 && res.status < 400) {
         const location = res.headers.get("location");
         if (location) {
-            res = await fetch(location, { ...init });
+            // Resolve the redirect target against the original URL so a relative
+            // `Location` header is handled correctly.
+            const resolved = new URL(location, url).toString();
+            // Cross-origin redirects must not receive the `Authorization` header
+            // (or any other auth-bearing headers) — otherwise a misconfigured /
+            // malicious redirect could exfiltrate the user's `osk_` API key to an
+            // arbitrary host.
+            const nextInit = sameOrigin(url, resolved) ? { ...init } : stripAuthHeaders(init);
+            res = await fetch(resolved, nextInit);
         }
     }
     return res;
 }
+function stripAuthHeaders(init) {
+    const headers = new Headers(init.headers ?? {});
+    headers.delete("authorization");
+    headers.delete("cookie");
+    headers.delete("proxy-authorization");
+    return { ...init, headers };
+}
+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 +199,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 +233,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/expansion.js

@@ -32,6 +32,9 @@ async function personLinkedinEnrich(params) {
     if (!url && !username) {
         throw new Error("[orangeslice] person.linkedin.enrich: provide url or username");
     }
+    if (url && !username) {
+        throw new Error(`[orangeslice] person.linkedin.enrich: URL must be a personal LinkedIn profile (linkedin.com/in/<username>), got: ${url}`);
+    }
     const sql = extended
         ? `SELECT lkd.*
          FROM linkedin_profile_slug ps

package/dist/generateObject.js

@@ -21,9 +21,14 @@ const api_1 = require("./api");
  * // { object: { company: "Apple Inc", year: 1976, founder: "Steve Jobs" } }
  */
 async function generateObject(options) {
-    return (0, api_1.post)("/execute/llm", {
+    const payload = {
         mode: "object",
         prompt: options.prompt,
         schemaJson: options.schema
-    });
+    };
+    if (options.system !== undefined)
+        payload.system = options.system;
+    if (options.model !== undefined)
+        payload.model = options.model;
+    return (0, api_1.post)("/execute/llm", payload);
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { configure } from "./api";
+export { configure, withApiKey } from "./api";
 export type { OrangesliceConfig } from "./api";
 export { integrations } from "./integrations";
 export type { Integration, IntegrationProvider, IntegrationListParams, IntegrationCreateParams, IntegrationUpdateParams, IntegrationConnectOptions, IntegrationExecuteOptions } from "./integrations";
@@ -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/dist/index.js

@@ -1,8 +1,9 @@
 "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.OCEAN_OPERATION_IDS = exports.oceanSearchPeople = exports.oceanSearchCompanies = exports.executeOcean = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.scrapeCareersPage = exports.findCareersPage = exports.skills = exports.integrations = 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.OCEAN_OPERATION_IDS = exports.oceanSearchPeople = exports.oceanSearchCompanies = exports.executeOcean = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.scrapeCareersPage = exports.findCareersPage = exports.skills = exports.integrations = exports.withApiKey = exports.configure = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return api_1.configure; } });
+Object.defineProperty(exports, "withApiKey", { enumerable: true, get: function () { return api_1.withApiKey; } });
 var integrations_1 = require("./integrations");
 Object.defineProperty(exports, "integrations", { enumerable: true, get: function () { return integrations_1.integrations; } });
 var skills_1 = require("./skills");

package/docs/integrations/index.md

@@ -240,6 +240,54 @@ 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 later
+const tracked = await integrations.websiteTracking.listTrackedDomains();
+
+// "Stop on THIS sheet only" — keeps the upstream allow-list up and
+// any other Orange Slice spreadsheets that enrolled the same domain
+// keep receiving visitor rows.
+await integrations.websiteTracking.detachTracking("acme.com");
+
+// "Stop tracking this domain on all my spreadsheets" — deletes every
+// Website Visitors trigger + mapping for the domain across all of
+// this account's spreadsheets. Other accounts that enrolled the same
+// domain are unaffected; the upstream allow-list is only dropped when
+// no other account still needs it.
+await integrations.websiteTracking.removeTracking("acme.com");
+
+// After a customer tops up, re-enable any paused mappings:
+const { resumed, alreadyActive, failures } =
+   await integrations.websiteTracking.resumeTracking();
+```
+
+Pricing: **80 credits per identified visitor** (charged at the master
+webhook). Charging happens ONCE per ping even when the same account
+enrolled the domain on multiple spreadsheets — the row fans out to
+every matching trigger under a single credit reservation. 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. **Resume is not automatic** — call
+`resumeTracking()` (optionally scoped to one domain) once the customer
+has topped up, otherwise the next top-up won't bring tracking back online.
+
+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,181 @@
+---
+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.
+
+- **Per-account tracking script** (`https://www.orangeslice.ai/wt.js?accountId=…`)
+  is pasted on the customer's site. The `accountId` round-trips back to
+  us as RB2B's `customer_id` on every ping, so even when multiple
+  Orange Slice accounts have enrolled the same domain, the ping is
+  routed only to the account that actually installed the script on
+  that page. No per-customer external account, no logins, no separate
+  billing. The script is provider-agnostic — if Orange Slice ever
+  swaps the underlying identification provider, the customer's pasted
+  snippet keeps working without any change.
+- Every visitor ping fans out to a **master webhook** we own. The
+  master webhook looks up `(captured domain, customer_id)`, charges the
+  customer's Orange Slice credit balance ONCE, then forwards the
+  visitor record to every trigger that this account enrolled for the
+  domain (one ping → one charge → N sheet rows when the same account
+  enrolled the domain on N spreadsheets).
+
+## Pricing
+
+**80 credits per non-repeat visitor.** Every distinct visit Orange
+Slice's tracking partner reports is charged, including:
+
+- Full identifications (LinkedIn URL + first name resolved), AND
+- Company-only matches (the visiting company is resolved but no
+  specific person).
+
+Repeat visits from the same person/device are forwarded to the sheet
+for context but NEVER charge credits.
+
+Every row written to the sheet still includes whatever fields the
+upstream resolved — column code can branch on `v.linkedinUrl !== null`
+if the customer wants to filter out company-only rows downstream.
+
+When the customer's balance hits zero, the master webhook automatically
+pauses their domain so they stop incurring charges. **Resume is not
+automatic** — after the customer tops up, the agent must explicitly call
+`integrations.websiteTracking.resumeTracking()` to re-enable tracking.
+The customer never has to re-paste the script.
+
+If a customer mentions topping up credits or wanting their tracking
+turned back on, check `listTrackedDomains()` — any mapping with
+`status: "disabled_no_credits"` needs `resumeTracking()` to come back to
+life.
+
+## 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 the destination sheet on the spreadsheet if it doesn't exist
+   yet (matched case-insensitively by name).
+2. Creates a sheet-aware trigger that ingests visitor payloads into that
+   sheet (uses `addRows` with `createMissingColumns: true` so the user
+   doesn't have to pre-create columns either).
+3. Inserts the domain → trigger mapping into our master routing table.
+4. Calls the upstream allow-list API to register the domain.
+5. Returns the per-account
+   `<script src="https://www.orangeslice.ai/wt.js?accountId=…">`
+   wrapper for the user to paste on their site. The `accountId` query
+   param is what scopes inbound pings to this account so a squatter
+   who also enrolled the domain cannot steal traffic from pages that
+   load this exact tag.
+
+If the same (domain, spreadsheet) is re-enrolled it is idempotent —
+the existing trigger and mapping are reused. If the user previously
+deleted the sheet, the helper re-creates it.
+
+## 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, multiple spreadsheets
+
+A single account can track many domains, each with its own trigger and
+sheet — call `setupTracking` once per domain.
+
+A single account can ALSO track the same domain on multiple
+spreadsheets (for example, sales-ops on one sheet and a marketing
+analyst on another). Each `setupTracking` call on a different
+spreadsheet creates its own trigger + mapping. When a visitor ping
+arrives, **80 credits are charged once** and the visitor row is fanned
+out to every matching trigger.
+
+Multiple Orange Slice accounts can also enroll the same domain — there
+is no cross-account block. Routing is disambiguated by the `accountId`
+baked into the `<script>` tag (RB2B receives it as `customer_id` and
+echoes it back on every ping), so pings only land on the account that
+actually installed the pixel.
+
+## Inspecting / removing
+
+```typescript
+// What's tracked on this spreadsheet? Returns active AND paused
+// (`disabled_no_credits`) mappings — check the `status` field.
+const mappings = await integrations.websiteTracking.listTrackedDomains();
+
+// "Stop tracking on THIS sheet only" — keep the upstream allow-list
+// up so other spreadsheets / accounts that enrolled the same domain
+// keep receiving visitor rows. The destination sheet keeps the
+// customer's existing visitor rows.
+await integrations.websiteTracking.detachTracking("acme.com");
+
+// "Stop tracking this domain on all my spreadsheets" — deletes every
+// Website Visitors trigger + mapping for that domain across ALL of
+// this account's spreadsheets. Other Orange Slice accounts that
+// co-enrolled the same domain are unaffected. The upstream allow-list
+// is only dropped if no other account still has the domain active.
+await integrations.websiteTracking.removeTracking("acme.com");
+```
+
+### Picking between `detachTracking` and `removeTracking`
+
+Both are scoped to the calling account — no caller can affect another
+account's mappings, so picking the wrong one is recoverable.
+
+- "Remove tracking from this sheet but keep my other sheet running" /
+  "I don't want visitors landing here anymore" / "delete this sheet's
+  Website Visitors trigger" → **`detachTracking(domain)`** (this
+  spreadsheet only).
+- "Turn off tracking for acme.com entirely" / "we sold this domain" /
+  "stop all visitor identification for acme.com" →
+  **`removeTracking(domain)`** (every spreadsheet under this account).
+- If the user has the same domain on multiple of THEIR spreadsheets
+  and the intent is ambiguous, ASK — `removeTracking` will tear down
+  all of them, whereas `detachTracking` is per-sheet surgical.
+
+## Resuming a paused domain (after a top-up)
+
+```typescript
+// Re-enable every paused mapping on this spreadsheet:
+const result = await integrations.websiteTracking.resumeTracking();
+
+// Or scope to one domain:
+const result = await integrations.websiteTracking.resumeTracking("acme.com");
+
+// result shape:
+// {
+//   resumed:       [{ domain, mappingId }],  // flipped back to active
+//   alreadyActive: [{ domain, mappingId }],  // already running, no-op
+//   failures:      [{ domain, mappingId, error }],  // upstream rejected
+// }
+```
+
+Only mappings currently in `status: "disabled_no_credits"` get resumed.
+Already-active mappings are reported in `alreadyActive` and not touched.
+The upstream allow-list call is idempotent — calling resume on a domain
+the provider already considers active is safe and ends up in
+`alreadyActive` after the conditional DB update.
+
+Tell the user how many domains came back online (`result.resumed.length`)
+and surface any `result.failures[].error` messages — those usually mean
+the upstream provider rejected the re-enrollment and need a human look.
+
+See [setupTracking.md](./setupTracking.md) for the full input/output
+contract.

package/docs/integrations/websiteTracking/setupTracking.md

@@ -0,0 +1,142 @@
+---
+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 (see below)
+   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
+}
+```
+
+The returned `script` is the per-account wrapper:
+
+```html
+<script src="https://www.orangeslice.ai/wt.js?accountId=<uuid>" async></script>
+```
+
+`/wt.js` is an Orange Slice-owned route that reads the active tracking
+provider at request time and injects the appropriate pixel. The
+`accountId` query param is what scopes inbound pings to the calling
+account (round-trips as RB2B's `customer_id`), so multiple Orange Slice
+accounts can safely co-enroll the same domain without stealing each
+other's traffic. If we ever swap the underlying provider, the
+customer's pasted snippet keeps working without any action on their
+end.
+
+## Errors
+
+- `Invalid domain` — `domain` couldn't be normalized to a host with a TLD.
+- `Concurrent setupTracking for "<x>" on this spreadsheet — retry.` —
+  a parallel `setupTracking` for the same (domain, spreadsheet) raced
+  ahead; re-run the call to pick up the now-live row idempotently.
+
+`setupTracking` no longer blocks cross-account enrollment: any account
+can enroll any domain, and a single account can enroll the same domain
+on multiple spreadsheets.
+
+## 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.
+
+The destination sheet is **created automatically** if it doesn't already
+exist on the spreadsheet — there's no pre-flight "make the sheet first"
+step the agent has to do. Existing sheets are matched case-insensitively
+by name and reused.
+
+## 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. Visitor rows will land in the "Website Visitors" sheet within
+//      ~5 minutes of installing.
+//   3. Each non-repeat visit costs 80 credits. This includes both
+//      full-person and company-only matches. Repeat visits from the
+//      same person are forwarded to the sheet but cost zero.
+//   4. If credits run out, tracking pauses automatically. After topping
+//      up they'll need to ask you to re-enable it — call
+//      `integrations.websiteTracking.resumeTracking()` when that happens.
+```
+
+## Pricing recap
+
+Charged once per ping where `isRepeatVisit` is not `true`. This
+includes both full-person identifications (`linkedinUrl` + `firstName`
+populated) AND company-only matches (only `companyName` / `website`
+populated).
+
+Cost: **80 credits per non-repeat visit**. Repeat visits are still
+forwarded to the sheet (so the user can analyze recurring traffic) but
+cost zero.
+
+If a customer wants to keep only full-person rows in their sheet, they
+can filter in column code: `if (!v.linkedinUrl) return null;` skips
+company-only rows before `addRows` writes them.

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",
+   "version": "2.6.0",
    "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",