orangeslice 2.5.0 → 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,42 @@ 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"`).

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";

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

@@ -255,15 +255,35 @@ const { script } = await integrations.websiteTracking.setupTracking({
    sheetName: "Website Visitors"
 });
 
-// Inspect / remove later
+// 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). 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.
+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.

package/docs/integrations/websiteTracking/index.md

@@ -10,24 +10,48 @@ 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.
+- **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 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.
+  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 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.
+**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. The next top-up
-resumes the domain automatically — the customer doesn't have to re-paste
-the script.
+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)
 
@@ -42,15 +66,23 @@ const { script, triggerId } = await integrations.websiteTracking.setupTracking({
 
 `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.
+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
 
@@ -63,24 +95,87 @@ trigger and mapping are reused.
    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 sites, multiple spreadsheets
 
 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).
+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?
+// 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 a domain.
+// "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

@@ -25,23 +25,42 @@ both store as `acme.com`.
 
 ```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
+   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.
-- `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).
+- `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
 
@@ -52,6 +71,11 @@ 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
@@ -92,19 +116,27 @@ const result = await integrations.websiteTracking.setupTracking({
 
 // 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.
+//   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:
-- `linkedinUrl` is present, AND
-- `firstName` is present, AND
-- `isRepeatVisit` is not `true`.
+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.
 
-Cost: **80 credits**. Company-only and 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/package.json

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