within-sdk 1.0.0 → 1.0.1

package/LICENSE

@@ -1 +1 @@
-MIT
+MIT

package/README.md

@@ -1,77 +1,211 @@
-# Within SDK
-
-MCP analytics and workflow-intelligence SDK for Within.
-
-```ts
-import { track } from "within-sdk";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-const server = new McpServer({ name: "acme-mcp", version: "1.0.0" });
-
-track(server, "acme", {
-  apiKey: process.env.WITHIN_SDK_API_KEY!,
-  identify: async (request) => {
-    const user = await lookupUser(request);
-    return {
-      userId: user.internalCustomerId,
-      userData: {
-        plan: user.plan,
-        segment: user.segment,
-      },
-    };
-  },
-});
-```
-
-`track(server, vendorSlug, options)` instruments MCP initialize, tools/list, and
-tools/call activity. The default instrumentation includes:
-
-- tracing is enabled
-- tool-call `context` capture is enabled
-- the `get_more_tools` feedback tool is enabled
-
-Events are posted only to Within. `options.apiBaseUrl` overrides the default
-ingestion host; otherwise the SDK checks `WITHIN_SDK_API_URL`, then
-`WITHIN_SDK_INGEST_BASE_URL`.
-
-## Privacy
-
-`identify()` keeps the existing public shape, while Within hashes `userId` locally
-with the vendor slug before enqueueing or posting telemetry. Raw `userId` and
-`userName` are not sent. `userData`, parameters, responses, tags, and properties
-are stripped of direct identity fields and redacted/truncated before they reach
-Within or vendor-configured exporters.
-
-Within ingestion also runs server-side Presidio redaction before SDK
-activity is stored. The first deployment is model-free: it uses Presidio
-rule/checksum/pattern recognizers for values such as emails, phones, SSNs,
-card-like values, URLs, IPs, bearer tokens, API keys, and secrets. It does not
-claim guaranteed detection of arbitrary names or locations without a later
-model-backed recognizer profile.
-
-## Conversion Reporting
-
-Report confirmed lead-to-subscriber conversion from trusted server-side code:
-
-```ts
-import { reportConversion } from "within-sdk";
-
-await reportConversion({
-  vendorSlug: "acme",
-  apiKey: process.env.WITHIN_SDK_API_KEY!,
-}, {
-  subject: user.internalCustomerId,
-  convertedAt: new Date(),
-  plan: {
-    id: "pro",
-    name: "Pro",
-    interval: "month",
-  },
-  metadata: {
-    source: "checkout_webhook",
-  },
-});
-```
-
-Conversion reporting hashes the subject locally and sends only the hash to
-Within.
+# Within SDK
+
+Instrument Model Context Protocol (MCP) servers with privacy-conscious workflow
+analytics. Within captures MCP activity, builds a catalog of available tools,
+groups pseudonymous user journeys, identifies qualified opportunities, and links
+confirmed conversions back to the workflows that produced them.
+
+[Documentation](https://apidocs.getwith.in) ·
+[Quickstart](https://apidocs.getwith.in/quickstart) ·
+[API Reference](https://apidocs.getwith.in/sdk/api-reference) ·
+[Get an API key](https://getwith.in/dashboard/signup)
+
+## Installation
+
+```bash
+npm install within-sdk @modelcontextprotocol/sdk
+```
+
+The SDK requires Node.js 20 or later and an MCP server using
+`@modelcontextprotocol/sdk` 1.11 or later.
+
+## Environment
+
+Configure the vendor slug created during onboarding and its SDK API key in the
+server process that runs your MCP server:
+
+```bash
+WITHIN_VENDOR_SLUG=acme
+WITHIN_SDK_API_KEY=within_sk_xxx
+```
+
+Keep the API key in server-side environment or secret storage. Do not expose it
+in browser code or commit it to source control.
+
+## Quickstart
+
+Register your MCP tools first, then call `track()` on the server instance used
+by the running process.
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { track } from "within-sdk";
+
+const server = new McpServer({ name: "acme-mcp", version: "1.0.0" });
+
+server.tool("search_companies", SearchCompaniesSchema, async (args) => {
+  return searchCompanies(args);
+});
+
+track(server, process.env.WITHIN_VENDOR_SLUG!, {
+  apiKey: process.env.WITHIN_SDK_API_KEY!,
+  identify: async (_request, extra) => {
+    const user = await lookupUserFromSession(extra?.sessionId);
+    if (!user) return null;
+
+    return {
+      userId: user.internalCustomerId,
+      userData: {
+        plan: user.plan,
+        segment: user.segment,
+      },
+    };
+  },
+});
+
+export { server };
+```
+
+Use a stable, opaque vendor-local ID for `userId` rather than an email address,
+name, or organization domain. The SDK hashes it locally with the vendor slug
+before telemetry leaves your process.
+
+By default, `track()` instruments MCP initialization, `tools/list`, and
+`tools/call` activity. It also enables tool-call context capture and registers
+the `get_more_tools` feedback tool without changing the results returned to MCP
+clients.
+
+## Public APIs
+
+### `track()`
+
+```ts
+track(server, vendorSlug, options?): server
+```
+
+Instruments a high-level `McpServer` or compatible low-level MCP server and
+returns the same server instance. Call it once for each server instance after
+registering tools.
+
+### `publishCustomEvent()`
+
+Publish a vendor-defined workflow event associated with a tracked server:
+
+```ts
+import { publishCustomEvent } from "within-sdk";
+
+await publishCustomEvent(server, "acme", {
+  resourceName: "checkout_started",
+  parameters: { plan: "pro" },
+  message: "User started checkout after an MCP workflow",
+  tags: { channel: "mcp" },
+});
+```
+
+When passed a tracked server, the function reuses its session, API key, and
+ingestion URL. You can also pass an MCP session ID string and provide `apiKey`
+in the event data.
+
+### `reportConversion()`
+
+Report a confirmed lead-to-subscriber conversion from trusted server-side
+checkout, webhook, or account-upgrade code:
+
+```ts
+import { reportConversion } from "within-sdk";
+
+const result = await reportConversion(
+  {
+    vendorSlug: process.env.WITHIN_VENDOR_SLUG!,
+    apiKey: process.env.WITHIN_SDK_API_KEY!,
+  },
+  {
+    subject: user.internalCustomerId,
+    convertedAt: new Date(),
+    plan: {
+      id: "pro",
+      name: "Pro",
+      interval: "month",
+    },
+    metadata: {
+      source: "checkout_webhook",
+    },
+  },
+);
+```
+
+Only `subject` is required. Use the same opaque subject used by `identify()`;
+the SDK hashes it locally before sending the report. Repeated reports for the
+same subject on the same UTC day return `inserted: false`.
+
+### `hashWithinSubject()`
+
+Generate the same vendor-scoped subject hash used by identification and
+conversion reporting. This is useful for tests and local verification.
+
+```ts
+import { hashWithinSubject } from "within-sdk";
+
+const subjectHash = hashWithinSubject("acme", user.internalCustomerId);
+```
+
+## Configuration
+
+`track(server, vendorSlug, options)` accepts these commonly used options:
+
+| Option | Purpose |
+| --- | --- |
+| `apiKey` | Within SDK API key. Falls back to `WITHIN_SDK_API_KEY`, then `WITHIN_SDK_INGEST_KEY`. |
+| `apiBaseUrl` | Override the Within ingestion URL. Most integrations should use the default. |
+| `identify` | Resolve a stable vendor-local subject and optional redacted traits for the current request. |
+| `enableTracing` | Capture supported MCP activity. Defaults to `true`. |
+| `enableToolCallContext` | Add and capture the tool-call `context` parameter. Defaults to `true`. |
+| `customContextDescription` | Replace the default description shown for the injected `context` parameter. |
+| `enableReportMissing` | Register the `get_more_tools` feedback tool. Defaults to `true`. |
+| `eventTags` | Add validated string tags to captured activity. |
+| `eventProperties` | Add custom properties to captured activity. |
+| `redactSensitiveInformation` | Apply an additional vendor-provided redaction function. |
+| `privacy` | Configure field/event byte limits and additional keys to redact. |
+| `exporters` | Send redacted telemetry to optional vendor-configured exporters. |
+
+`apiBaseUrl` falls back to `WITHIN_SDK_API_URL`, then
+`WITHIN_SDK_INGEST_BASE_URL`, and finally the default Within ingestion service.
+See the [API Reference](https://apidocs.getwith.in/sdk/api-reference) for the
+complete option and result types.
+
+## Privacy and redaction
+
+- `userId` and conversion subjects are hashed locally with the vendor slug.
+- Raw `userId` and `userName` values are not sent to Within.
+- Identity-like fields in user data, parameters, responses, tags, properties,
+  and conversion metadata are removed or redacted before sending.
+- Configurable field and event limits truncate oversized payloads.
+- Within ingestion applies an additional server-side Presidio redaction pass
+  for recognized values such as emails, phone numbers, SSNs, card-like values,
+  URLs, IPs, bearer tokens, API keys, and secrets.
+
+Pattern-based redaction cannot guarantee detection of every possible name,
+location, or sensitive value. Send only data needed for workflow analytics and
+use opaque identifiers whenever possible.
+
+## Documentation
+
+- [Within SDK documentation](https://apidocs.getwith.in)
+- [Quickstart](https://apidocs.getwith.in/quickstart)
+- [API Reference](https://apidocs.getwith.in/sdk/api-reference)
+- [Configuration](https://apidocs.getwith.in/sdk/configuration)
+- [Privacy and redaction](https://apidocs.getwith.in/sdk/privacy-redaction)
+- [Troubleshooting](https://apidocs.getwith.in/troubleshooting)
+
+## Onboarding: Sign up and get an API key
+
+1. [Create a Within dashboard account](https://getwith.in/dashboard/signup)
+   using your work email, vendor name, and vendor slug.
+2. Enter the confirmation code sent to your email, then sign in to the Within
+   dashboard.
+3. Open **Settings**, select your vendor, and choose **Generate** under
+   **SDK API Key**.
+4. Copy the newly displayed key and store it securely. The dashboard does not
+   retain the plaintext key for later display.
+5. Set the key as `WITHIN_SDK_API_KEY`, set your registered slug as
+   `WITHIN_VENDOR_SLUG`, and use both values in `track()`.

package/dist/thirdparty/ksuid/base-convert-int-array.js

@@ -1,49 +1,49 @@
-"use strict";
-
-const maxLength = (array, from, to) =>
-  Math.ceil((array.length * Math.log2(from)) / Math.log2(to));
-
-function baseConvertIntArray(array, { from, to, fixedLength = null }) {
-  const length =
-    fixedLength === null ? maxLength(array, from, to) : fixedLength;
-  const result = new Array(length);
-
-  // Each iteration prepends the resulting value, so start the offset at the end.
-  let offset = length;
-  let input = array;
-  while (input.length > 0) {
-    if (offset === 0) {
-      throw new RangeError(
-        `Fixed length of ${fixedLength} is too small, expected at least ${maxLength(array, from, to)}`,
-      );
-    }
-
-    const quotients = [];
-    let remainder = 0;
-
-    for (const digit of input) {
-      const acc = digit + remainder * from;
-      const q = Math.floor(acc / to);
-      remainder = acc % to;
-
-      if (quotients.length > 0 || q > 0) {
-        quotients.push(q);
-      }
-    }
-
-    result[--offset] = remainder;
-    input = quotients;
-  }
-
-  // Trim leading padding, unless length is fixed.
-  if (fixedLength === null) {
-    return offset > 0 ? result.slice(offset) : result;
-  }
-
-  // Fill in any holes in the result array.
-  while (offset > 0) {
-    result[--offset] = 0;
-  }
-  return result;
-}
-export default baseConvertIntArray;
+"use strict";
+
+const maxLength = (array, from, to) =>
+  Math.ceil((array.length * Math.log2(from)) / Math.log2(to));
+
+function baseConvertIntArray(array, { from, to, fixedLength = null }) {
+  const length =
+    fixedLength === null ? maxLength(array, from, to) : fixedLength;
+  const result = new Array(length);
+
+  // Each iteration prepends the resulting value, so start the offset at the end.
+  let offset = length;
+  let input = array;
+  while (input.length > 0) {
+    if (offset === 0) {
+      throw new RangeError(
+        `Fixed length of ${fixedLength} is too small, expected at least ${maxLength(array, from, to)}`,
+      );
+    }
+
+    const quotients = [];
+    let remainder = 0;
+
+    for (const digit of input) {
+      const acc = digit + remainder * from;
+      const q = Math.floor(acc / to);
+      remainder = acc % to;
+
+      if (quotients.length > 0 || q > 0) {
+        quotients.push(q);
+      }
+    }
+
+    result[--offset] = remainder;
+    input = quotients;
+  }
+
+  // Trim leading padding, unless length is fixed.
+  if (fixedLength === null) {
+    return offset > 0 ? result.slice(offset) : result;
+  }
+
+  // Fill in any holes in the result array.
+  while (offset > 0) {
+    result[--offset] = 0;
+  }
+  return result;
+}
+export default baseConvertIntArray;

package/dist/thirdparty/ksuid/base62.js

@@ -1,24 +1,24 @@
-"use strict";
-import baseConvertIntArray from "./base-convert-int-array.js";
-
-const CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-
-function encode(buffer, fixedLength) {
-  return baseConvertIntArray(buffer, { from: 256, to: 62, fixedLength })
-    .map((value) => CHARS[value])
-    .join("");
-}
-
-function decode(string, fixedLength) {
-  // Optimization from https://github.com/andrew/base62.js/pull/31.
-  const input = Array.from(string, (char) => {
-    const charCode = char.charCodeAt(0);
-    if (charCode < 58) return charCode - 48;
-    if (charCode < 91) return charCode - 55;
-    return charCode - 61;
-  });
-  return Buffer.from(
-    baseConvertIntArray(input, { from: 62, to: 256, fixedLength }),
-  );
-}
-export { encode, decode };
+"use strict";
+import baseConvertIntArray from "./base-convert-int-array.js";
+
+const CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+function encode(buffer, fixedLength) {
+  return baseConvertIntArray(buffer, { from: 256, to: 62, fixedLength })
+    .map((value) => CHARS[value])
+    .join("");
+}
+
+function decode(string, fixedLength) {
+  // Optimization from https://github.com/andrew/base62.js/pull/31.
+  const input = Array.from(string, (char) => {
+    const charCode = char.charCodeAt(0);
+    if (charCode < 58) return charCode - 48;
+    if (charCode < 91) return charCode - 55;
+    return charCode - 61;
+  });
+  return Buffer.from(
+    baseConvertIntArray(input, { from: 62, to: 256, fixedLength }),
+  );
+}
+export { encode, decode };

package/dist/thirdparty/ksuid/index.d.ts

@@ -1,30 +1,30 @@
-/// <reference types="node" />
-declare class KSUID {
-  constructor(buffer: Buffer);
-  readonly raw: Buffer;
-  readonly date: Date;
-  readonly timestamp: number;
-  readonly payload: Buffer;
-  readonly string: string;
-  compare(other: KSUID): number;
-  equals(other: KSUID): boolean;
-  toString(): string;
-  toJSON(): string;
-  static random(): Promise<KSUID>;
-  static random(timeInMs: number): Promise<KSUID>;
-  static random(date: Date): Promise<KSUID>;
-  static randomSync(): KSUID;
-  static randomSync(timeInMs: number): KSUID;
-  static randomSync(date: Date): KSUID;
-  static fromParts(timeInMs: number, payload: Buffer): KSUID;
-  static isValid(buffer: Buffer): boolean;
-  static parse(str: string): KSUID;
-  static withPrefix(prefix: string): {
-    random(timeInMs?: number): Promise<string>;
-    random(date?: Date): Promise<string>;
-    randomSync(timeInMs?: number): string;
-    randomSync(date?: Date): string;
-    fromParts(timeInMs: number, payload: Buffer): string;
-  };
-}
-export default KSUID;
+/// <reference types="node" />
+declare class KSUID {
+  constructor(buffer: Buffer);
+  readonly raw: Buffer;
+  readonly date: Date;
+  readonly timestamp: number;
+  readonly payload: Buffer;
+  readonly string: string;
+  compare(other: KSUID): number;
+  equals(other: KSUID): boolean;
+  toString(): string;
+  toJSON(): string;
+  static random(): Promise<KSUID>;
+  static random(timeInMs: number): Promise<KSUID>;
+  static random(date: Date): Promise<KSUID>;
+  static randomSync(): KSUID;
+  static randomSync(timeInMs: number): KSUID;
+  static randomSync(date: Date): KSUID;
+  static fromParts(timeInMs: number, payload: Buffer): KSUID;
+  static isValid(buffer: Buffer): boolean;
+  static parse(str: string): KSUID;
+  static withPrefix(prefix: string): {
+    random(timeInMs?: number): Promise<string>;
+    random(date?: Date): Promise<string>;
+    randomSync(timeInMs?: number): string;
+    randomSync(date?: Date): string;
+    fromParts(timeInMs: number, payload: Buffer): string;
+  };
+}
+export default KSUID;