@waniwani/sdk 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -3,13 +3,60 @@ declare class WaniWaniError extends Error {
     constructor(message: string, status: number);
 }
 
+type MCPProvider = "openai" | "anthropic" | "unknown";
+/** OpenAI-specific MCP metadata structure */
+interface OpenAIMeta {
+    "openai/subject"?: string;
+    "openai/session"?: string;
+    "openai/userAgent"?: string;
+    "openai/locale"?: string;
+    "openai/userLocation"?: {
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+        latitude?: string;
+        longitude?: string;
+    };
+    timezone_offset_minutes?: number;
+}
+/** Location information (provider-agnostic) */
+interface LocationInfo {
+    city?: string;
+    region?: string;
+    country?: string;
+    timezone?: string;
+}
+/** Normalized metadata extracted from any MCP provider */
+interface NormalizedMeta {
+    provider: MCPProvider;
+    sessionId?: string;
+    externalUserId?: string;
+    userAgent?: string;
+    locale?: string;
+    location?: LocationInfo;
+}
 type EventType = "session.started" | "tool.called" | "quote.requested" | "quote.succeeded" | "quote.failed" | "link.clicked" | "purchase.completed";
 type ToolType = "pricing" | "product_info" | "availability" | "support" | "other";
 interface BaseEvent {
-    sessionId: string;
-    userAgent?: string;
-    externalUserId?: string;
-    metadata?: Record<string, unknown>;
+    /**
+     * MCP request metadata. The SDK auto-extracts provider fields
+     * (sessionId, userId, location, etc.). Can also include custom fields.
+     *
+     * Location varies by MCP library:
+     * - `@vercel/mcp-handler`: `extra._meta`
+     * - `@modelcontextprotocol/sdk`: `request.params._meta`
+     *
+     * @example
+     * ```typescript
+     * wani.track({
+     *   eventType: 'tool.called',
+     *   toolName: 'search',
+     *   meta: extra._meta,
+     * });
+     * ```
+     */
+    meta?: Record<string, unknown>;
 }
 type TrackEvent = ({
     eventType: "session.started";
@@ -38,19 +85,12 @@ type TrackEvent = ({
  */
 interface TrackingClient {
     /**
-     * Track an event using the WaniWani API
+     * Track an event. Pass MCP request metadata to auto-extract session, user,
+     * and location info from the provider (OpenAI, Anthropic, etc.).
      */
     track: (event: TrackEvent) => Promise<{
         eventId: string;
     }>;
-    /**
-     * Extract session ID from MCP request metadata, or generate a new one.
-     * If a new session ID is generated, automatically tracks a session.started event.
-     *
-     * @param meta - The _meta object from the MCP request (extra?._meta)
-     * @returns The session ID (existing or newly generated)
-     */
-    getOrCreateSession: (meta?: Record<string, unknown>) => Promise<string>;
 }
 
 interface WaniWaniConfig {
@@ -80,6 +120,15 @@ interface WaniWaniConfig {
 interface WaniWaniClient extends TrackingClient {
 }
 
+/**
+ * Detect which MCP provider sent the request based on metadata keys
+ */
+declare function detectProvider(meta: Record<string, unknown>): MCPProvider;
+/**
+ * Extract normalized metadata from any MCP provider's metadata
+ */
+declare function extractMetadata(meta: Record<string, unknown>): NormalizedMeta;
+
 /**
  * Create a WaniWani SDK client
  *
@@ -101,4 +150,4 @@ interface WaniWaniClient extends TrackingClient {
  */
 declare function waniwani(config?: WaniWaniConfig): WaniWaniClient;
 
-export { type EventType, type ToolType, type TrackEvent, type WaniWaniClient, type WaniWaniConfig, WaniWaniError, waniwani };
+export { type EventType, type LocationInfo, type MCPProvider, type NormalizedMeta, type OpenAIMeta, type ToolType, type TrackEvent, type WaniWaniClient, type WaniWaniConfig, WaniWaniError, detectProvider, extractMetadata, waniwani };

package/dist/index.js

@@ -1,2 +1,2 @@
-var o=class extends Error{constructor(t,s){super(t);this.status=s;this.name="WaniWaniError"}};function f(i){let{baseUrl:a,apiKey:t}=i;function s(){if(!t)throw new Error("WANIWANI_API_KEY is not set")}return{async track(e){try{s();let n=await fetch(`${a}/api/mcp/events`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${t}`},body:JSON.stringify(e)}),r=await n.json();if(!n.ok)throw new o(r.message??"Request failed",n.status);return{eventId:r.data.eventId}}catch(n){throw console.error("[WaniWani] Track error:",n),n}},async getOrCreateSession(e){if(e){let r=e["openai/sessionId"]||e.sessionId||e.conversationId;if(typeof r=="string"&&r.length>0)return r}let n=crypto.randomUUID();return await this.track({eventType:"session.started",sessionId:n}),n}}}function y(i){let a=i?.baseUrl??"https://app.waniwani.ai",t=i?.apiKey??process.env.WANIWANI_API_KEY;return{...f({baseUrl:a,apiKey:t})}}export{o as WaniWaniError,y as waniwani};
+var r=class extends Error{constructor(t,p){super(t);this.status=p;this.name="WaniWaniError"}};function f(e){return e["openai/subject"]||e["openai/session"]?"openai":"unknown"}function c(e){switch(f(e)){case"openai":return m(e);case"anthropic":return y(e);default:return{provider:"unknown"}}}function m(e){let n=e["openai/userLocation"],t;return n&&(t={city:n.city,region:n.region,country:n.country,timezone:n.timezone}),{provider:"openai",sessionId:e["openai/session"],externalUserId:e["openai/subject"],userAgent:e["openai/userAgent"],locale:e["openai/locale"],location:t}}function y(e){return{provider:"anthropic"}}function l(e){let{baseUrl:n,apiKey:t}=e;function p(){if(!t)throw new Error("WANIWANI_API_KEY is not set")}return{async track(o){try{p();let i=o.meta?c(o.meta):{},d=await fetch(`${n}/api/mcp/events`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${t}`},body:JSON.stringify({...o,...i})}),u=await d.json();if(!d.ok)throw new r(u.message??"Request failed",d.status);return{eventId:u.data.eventId}}catch(i){throw console.error("[WaniWani] Track error:",i),i}}}}function g(e){let n=e?.baseUrl??"https://app.waniwani.ai",t=e?.apiKey??process.env.WANIWANI_API_KEY;return{...l({baseUrl:n,apiKey:t})}}export{r as WaniWaniError,f as detectProvider,c as extractMetadata,g as waniwani};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/error.ts","../src/tracking/index.ts","../src/waniwani.ts"],"sourcesContent":["// WaniWani SDK - Errors\n\nexport class WaniWaniError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic status: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"WaniWaniError\";\n\t}\n}\n","// Tracking Module\n\nimport { WaniWaniError } from \"../error.js\";\nimport type { InternalConfig } from \"../types.js\";\nimport type { TrackEvent, TrackingClient } from \"./@types.js\";\n\n// Re-export types\nexport type {\n\tEventType,\n\tToolType,\n\tTrackEvent,\n\tTrackingClient,\n} from \"./@types.js\";\n\nexport function createTrackingClient(config: InternalConfig): TrackingClient {\n\tconst { baseUrl, apiKey } = config;\n\n\tfunction checkIfApiKeyIsSet() {\n\t\tif (!apiKey) {\n\t\t\tthrow new Error(\"WANIWANI_API_KEY is not set\");\n\t\t}\n\t}\n\n\treturn {\n\t\tasync track(event: TrackEvent): Promise<{ eventId: string }> {\n\t\t\ttry {\n\t\t\t\tcheckIfApiKeyIsSet();\n\n\t\t\t\tconst response = await fetch(`${baseUrl}/api/mcp/events`, {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: {\n\t\t\t\t\t\t\"Content-Type\": \"application/json\",\n\t\t\t\t\t\tAuthorization: `Bearer ${apiKey}`,\n\t\t\t\t\t},\n\t\t\t\t\tbody: JSON.stringify(event),\n\t\t\t\t});\n\n\t\t\t\tconst data = await response.json();\n\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\tthrow new WaniWaniError(\n\t\t\t\t\t\tdata.message ?? \"Request failed\",\n\t\t\t\t\t\tresponse.status,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\treturn { eventId: data.data.eventId };\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\"[WaniWani] Track error:\", error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t},\n\n\t\tasync getOrCreateSession(meta?: Record<string, unknown>): Promise<string> {\n\t\t\tif (meta) {\n\t\t\t\tconst sessionId =\n\t\t\t\t\tmeta[\"openai/sessionId\"] || meta.sessionId || meta.conversationId;\n\t\t\t\tif (typeof sessionId === \"string\" && sessionId.length > 0) {\n\t\t\t\t\treturn sessionId;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst sessionId = crypto.randomUUID();\n\t\t\tawait this.track({ eventType: \"session.started\", sessionId });\n\t\t\treturn sessionId;\n\t\t},\n\t};\n}\n","// WaniWani SDK - Main Entry\n\nimport { createTrackingClient } from \"./tracking/index.js\";\nimport type { WaniWaniClient, WaniWaniConfig } from \"./types.js\";\n\n/**\n * Create a WaniWani SDK client\n *\n * @param config - Configuration options\n * @returns A fully typed WaniWani client\n *\n * @example\n * ```typescript\n * import { waniwani } from \"@waniwani\";\n *\n * const client = waniwani({ apiKey: \"...\" });\n *\n * await client.track({\n *   eventType: \"tool.called\",\n *   sessionId: \"session-123\",\n *   toolName: \"pricing\"\n * });\n * ```\n */\nexport function waniwani(config?: WaniWaniConfig): WaniWaniClient {\n\tconst baseUrl = config?.baseUrl ?? \"https://app.waniwani.ai\";\n\tconst apiKey = config?.apiKey ?? process.env.WANIWANI_API_KEY;\n\n\tconst internalConfig = { baseUrl, apiKey };\n\n\t// Compose client from modules\n\tconst tracking = createTrackingClient(internalConfig);\n\n\treturn {\n\t\t...tracking,\n\t\t// Future modules will be spread here\n\t\t// ...tools,\n\t};\n}\n"],"mappings":"AAEO,IAAMA,EAAN,cAA4B,KAAM,CACxC,YACCC,EACOC,EACN,CACD,MAAMD,CAAO,EAFN,YAAAC,EAGP,KAAK,KAAO,eACb,CACD,ECIO,SAASC,EAAqBC,EAAwC,CAC5E,GAAM,CAAE,QAAAC,EAAS,OAAAC,CAAO,EAAIF,EAE5B,SAASG,GAAqB,CAC7B,GAAI,CAACD,EACJ,MAAM,IAAI,MAAM,6BAA6B,CAE/C,CAEA,MAAO,CACN,MAAM,MAAME,EAAiD,CAC5D,GAAI,CACHD,EAAmB,EAEnB,IAAME,EAAW,MAAM,MAAM,GAAGJ,CAAO,kBAAmB,CACzD,OAAQ,OACR,QAAS,CACR,eAAgB,mBAChB,cAAe,UAAUC,CAAM,EAChC,EACA,KAAM,KAAK,UAAUE,CAAK,CAC3B,CAAC,EAEKE,EAAO,MAAMD,EAAS,KAAK,EAEjC,GAAI,CAACA,EAAS,GACb,MAAM,IAAIE,EACTD,EAAK,SAAW,iBAChBD,EAAS,MACV,EAGD,MAAO,CAAE,QAASC,EAAK,KAAK,OAAQ,CACrC,OAASE,EAAO,CACf,cAAQ,MAAM,0BAA2BA,CAAK,EACxCA,CACP,CACD,EAEA,MAAM,mBAAmBC,EAAiD,CACzE,GAAIA,EAAM,CACT,IAAMC,EACLD,EAAK,kBAAkB,GAAKA,EAAK,WAAaA,EAAK,eACpD,GAAI,OAAOC,GAAc,UAAYA,EAAU,OAAS,EACvD,OAAOA,CAET,CAEA,IAAMA,EAAY,OAAO,WAAW,EACpC,aAAM,KAAK,MAAM,CAAE,UAAW,kBAAmB,UAAAA,CAAU,CAAC,EACrDA,CACR,CACD,CACD,CC3CO,SAASC,EAASC,EAAyC,CACjE,IAAMC,EAAUD,GAAQ,SAAW,0BAC7BE,EAASF,GAAQ,QAAU,QAAQ,IAAI,iBAO7C,MAAO,CACN,GAHgBG,EAHM,CAAE,QAAAF,EAAS,OAAAC,CAAO,CAGW,CAMpD,CACD","names":["WaniWaniError","message","status","createTrackingClient","config","baseUrl","apiKey","checkIfApiKeyIsSet","event","response","data","WaniWaniError","error","meta","sessionId","waniwani","config","baseUrl","apiKey","createTrackingClient"]}
+{"version":3,"sources":["../src/error.ts","../src/tracking/metadata.ts","../src/tracking/index.ts","../src/waniwani.ts"],"sourcesContent":["// WaniWani SDK - Errors\n\nexport class WaniWaniError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic status: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"WaniWaniError\";\n\t}\n}\n","// Metadata Extraction Module\n\nimport type {\n\tLocationInfo,\n\tMCPProvider,\n\tNormalizedMeta,\n\tOpenAIMeta,\n} from \"./@types.js\";\n\n/**\n * Detect which MCP provider sent the request based on metadata keys\n */\nexport function detectProvider(meta: Record<string, unknown>): MCPProvider {\n\tif (meta[\"openai/subject\"] || meta[\"openai/session\"]) {\n\t\treturn \"openai\";\n\t}\n\t// Add Anthropic detection when their MCP format is known\n\t// if (meta['anthropic/...']) return 'anthropic';\n\treturn \"unknown\";\n}\n\n/**\n * Extract normalized metadata from any MCP provider's metadata\n */\nexport function extractMetadata(meta: Record<string, unknown>): NormalizedMeta {\n\tconst provider = detectProvider(meta);\n\n\tswitch (provider) {\n\t\tcase \"openai\":\n\t\t\treturn extractOpenAIMeta(meta as unknown as OpenAIMeta);\n\t\tcase \"anthropic\":\n\t\t\treturn extractAnthropicMeta(meta);\n\t\tdefault:\n\t\t\treturn { provider: \"unknown\" };\n\t}\n}\n\nfunction extractOpenAIMeta(meta: OpenAIMeta): NormalizedMeta {\n\tconst rawLocation = meta[\"openai/userLocation\"];\n\tlet location: LocationInfo | undefined;\n\n\tif (rawLocation) {\n\t\tlocation = {\n\t\t\tcity: rawLocation.city,\n\t\t\tregion: rawLocation.region,\n\t\t\tcountry: rawLocation.country,\n\t\t\ttimezone: rawLocation.timezone,\n\t\t};\n\t}\n\n\treturn {\n\t\tprovider: \"openai\",\n\t\tsessionId: meta[\"openai/session\"],\n\t\texternalUserId: meta[\"openai/subject\"],\n\t\tuserAgent: meta[\"openai/userAgent\"],\n\t\tlocale: meta[\"openai/locale\"],\n\t\tlocation,\n\t};\n}\n\nfunction extractAnthropicMeta(_meta: Record<string, unknown>): NormalizedMeta {\n\t// Placeholder for Anthropic extraction logic\n\t// Will be implemented when Anthropic MCP metadata format is known\n\treturn { provider: \"anthropic\" };\n}\n","// Tracking Module\n\nimport { WaniWaniError } from \"../error.js\";\nimport type { InternalConfig } from \"../types.js\";\nimport type { TrackEvent, TrackingClient } from \"./@types.js\";\nimport { extractMetadata } from \"./metadata.js\";\n\n// Re-export types\nexport type {\n\tEventType,\n\tLocationInfo,\n\tMCPProvider,\n\tNormalizedMeta,\n\tOpenAIMeta,\n\tToolType,\n\tTrackEvent,\n\tTrackingClient,\n} from \"./@types.js\";\n\n// Re-export metadata utilities\nexport { detectProvider, extractMetadata } from \"./metadata.js\";\n\nexport function createTrackingClient(config: InternalConfig): TrackingClient {\n\tconst { baseUrl, apiKey } = config;\n\n\tfunction checkIfApiKeyIsSet() {\n\t\tif (!apiKey) {\n\t\t\tthrow new Error(\"WANIWANI_API_KEY is not set\");\n\t\t}\n\t}\n\n\treturn {\n\t\tasync track(event: TrackEvent): Promise<{ eventId: string }> {\n\t\t\ttry {\n\t\t\t\tcheckIfApiKeyIsSet();\n\n\t\t\t\t// Extract provider-specific fields from meta if present\n\t\t\t\tconst normalized = event.meta ? extractMetadata(event.meta) : {};\n\n\t\t\t\tconst response = await fetch(`${baseUrl}/api/mcp/events`, {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: {\n\t\t\t\t\t\t\"Content-Type\": \"application/json\",\n\t\t\t\t\t\tAuthorization: `Bearer ${apiKey}`,\n\t\t\t\t\t},\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\t...event,\n\t\t\t\t\t\t...normalized,\n\t\t\t\t\t}),\n\t\t\t\t});\n\n\t\t\t\tconst data = await response.json();\n\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\tthrow new WaniWaniError(\n\t\t\t\t\t\tdata.message ?? \"Request failed\",\n\t\t\t\t\t\tresponse.status,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\treturn { eventId: data.data.eventId };\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\"[WaniWani] Track error:\", error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t},\n\t};\n}\n","// WaniWani SDK - Main Entry\n\nimport { createTrackingClient } from \"./tracking/index.js\";\nimport type { WaniWaniClient, WaniWaniConfig } from \"./types.js\";\n\n/**\n * Create a WaniWani SDK client\n *\n * @param config - Configuration options\n * @returns A fully typed WaniWani client\n *\n * @example\n * ```typescript\n * import { waniwani } from \"@waniwani\";\n *\n * const client = waniwani({ apiKey: \"...\" });\n *\n * await client.track({\n *   eventType: \"tool.called\",\n *   sessionId: \"session-123\",\n *   toolName: \"pricing\"\n * });\n * ```\n */\nexport function waniwani(config?: WaniWaniConfig): WaniWaniClient {\n\tconst baseUrl = config?.baseUrl ?? \"https://app.waniwani.ai\";\n\tconst apiKey = config?.apiKey ?? process.env.WANIWANI_API_KEY;\n\n\tconst internalConfig = { baseUrl, apiKey };\n\n\t// Compose client from modules\n\tconst tracking = createTrackingClient(internalConfig);\n\n\treturn {\n\t\t...tracking,\n\t\t// Future modules will be spread here\n\t\t// ...tools,\n\t};\n}\n"],"mappings":"AAEO,IAAMA,EAAN,cAA4B,KAAM,CACxC,YACCC,EACOC,EACN,CACD,MAAMD,CAAO,EAFN,YAAAC,EAGP,KAAK,KAAO,eACb,CACD,ECEO,SAASC,EAAeC,EAA4C,CAC1E,OAAIA,EAAK,gBAAgB,GAAKA,EAAK,gBAAgB,EAC3C,SAID,SACR,CAKO,SAASC,EAAgBD,EAA+C,CAG9E,OAFiBD,EAAeC,CAAI,EAElB,CACjB,IAAK,SACJ,OAAOE,EAAkBF,CAA6B,EACvD,IAAK,YACJ,OAAOG,EAAqBH,CAAI,EACjC,QACC,MAAO,CAAE,SAAU,SAAU,CAC/B,CACD,CAEA,SAASE,EAAkBF,EAAkC,CAC5D,IAAMI,EAAcJ,EAAK,qBAAqB,EAC1CK,EAEJ,OAAID,IACHC,EAAW,CACV,KAAMD,EAAY,KAClB,OAAQA,EAAY,OACpB,QAASA,EAAY,QACrB,SAAUA,EAAY,QACvB,GAGM,CACN,SAAU,SACV,UAAWJ,EAAK,gBAAgB,EAChC,eAAgBA,EAAK,gBAAgB,EACrC,UAAWA,EAAK,kBAAkB,EAClC,OAAQA,EAAK,eAAe,EAC5B,SAAAK,CACD,CACD,CAEA,SAASF,EAAqBG,EAAgD,CAG7E,MAAO,CAAE,SAAU,WAAY,CAChC,CC1CO,SAASC,EAAqBC,EAAwC,CAC5E,GAAM,CAAE,QAAAC,EAAS,OAAAC,CAAO,EAAIF,EAE5B,SAASG,GAAqB,CAC7B,GAAI,CAACD,EACJ,MAAM,IAAI,MAAM,6BAA6B,CAE/C,CAEA,MAAO,CACN,MAAM,MAAME,EAAiD,CAC5D,GAAI,CACHD,EAAmB,EAGnB,IAAME,EAAaD,EAAM,KAAOE,EAAgBF,EAAM,IAAI,EAAI,CAAC,EAEzDG,EAAW,MAAM,MAAM,GAAGN,CAAO,kBAAmB,CACzD,OAAQ,OACR,QAAS,CACR,eAAgB,mBAChB,cAAe,UAAUC,CAAM,EAChC,EACA,KAAM,KAAK,UAAU,CACpB,GAAGE,EACH,GAAGC,CACJ,CAAC,CACF,CAAC,EAEKG,EAAO,MAAMD,EAAS,KAAK,EAEjC,GAAI,CAACA,EAAS,GACb,MAAM,IAAIE,EACTD,EAAK,SAAW,iBAChBD,EAAS,MACV,EAGD,MAAO,CAAE,QAASC,EAAK,KAAK,OAAQ,CACrC,OAASE,EAAO,CACf,cAAQ,MAAM,0BAA2BA,CAAK,EACxCA,CACP,CACD,CACD,CACD,CC3CO,SAASC,EAASC,EAAyC,CACjE,IAAMC,EAAUD,GAAQ,SAAW,0BAC7BE,EAASF,GAAQ,QAAU,QAAQ,IAAI,iBAO7C,MAAO,CACN,GAHgBG,EAHM,CAAE,QAAAF,EAAS,OAAAC,CAAO,CAGW,CAMpD,CACD","names":["WaniWaniError","message","status","detectProvider","meta","extractMetadata","extractOpenAIMeta","extractAnthropicMeta","rawLocation","location","_meta","createTrackingClient","config","baseUrl","apiKey","checkIfApiKeyIsSet","event","normalized","extractMetadata","response","data","WaniWaniError","error","waniwani","config","baseUrl","apiKey","createTrackingClient"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waniwani/sdk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "WaniWani SDK - MCP event tracking and tools",
   "type": "module",
   "exports": {