trackly-cli 0.21.0 → 0.21.2

package/README.md

@@ -353,7 +353,9 @@ a missing capability. Run `trackly mcp` or use
 
 MCP usage analytics are on by default and relay through Trackly so the free
 service can be debugged and improved. They exclude résumé text, profile answers,
-demographic or work-authorization answers, and application notes. Turn off future
+demographic or work-authorization answers, and application notes. Client attribution
+uses a fixed family label; errors use categories, and search text is retained only
+as length. Raw queries and conversation text are excluded. Turn off future
 collection with **Share usage analytics** in Account Settings. Operators may also
 disable local MCP instrumentation with `TRACKLY_MCP_ANALYTICS_DISABLED=1` (or
 `TRACKLY_MCP_ANALYTICS_ENABLED=0`); the account setting remains authoritative

package/docs/solutions/integration-issues/analytics-must-preserve-strict-mcp-schemas.md

@@ -37,3 +37,17 @@ Verification: `node --test test/mcp-analytics.test.js test/mcp-schema.test.js`
 and `npm test`. The real transport regression failed with the old instrumentation
 and passed after the fix. Keyword telemetry continues to retain length only;
 this change does not permit raw query or context storage.
+
+Error and client attribution also need real SDK coverage. The SDK's error type
+may be a JavaScript constructor name, and its vendor field comes from HTTP
+headers that stdio does not have. Normalize both at the privacy boundary:
+derive a closed error category from the failure and a closed client family from
+available metadata, with explicit `none`, `other` and `unknown` states.
+
+The HTTP client rejects response records containing numeric status and an
+`error` field. Capturing only `message` loses that status and substitutes a
+generic fallback. Preserve the status in the telemetry-only exception and give
+it precedence over endpoint words such as "network brief". Verify job detail
+and brief calls through a local HTTP fixture with 404, 429 and 500 responses;
+assert unchanged tool results and classified, content-free telemetry. Sanitize
+the result twice because the SDK hook and backend relay both project events.

package/docs/trackly-tools.md

@@ -80,9 +80,9 @@ API-key creation attempts.
   - `caProvinces`: nonempty array of `AB`, `BC`, `MB`, `NB`, `NL`, `NS`, `NT`, `NU`, `ON`, `PE`, `QC`, `SK`, `YT`, `REMOTE`. Geographic children follow the backend location rollout: parent-scoped OR applies under canonical enforcement; legacy compatibility remains before that. `REMOTE` alongside codes also includes remote jobs.
   - `internshipLevels`: nonempty array of `undergraduate`, `graduate`, `mba`, `not_specified`, combined with OR. Applies to internships when `jobModality=internship` or `all`; full-time jobs remain unaffected. Set `jobModality` explicitly when you want internships; education levels do not change your saved/default modality.
   - `favoriteCompaniesOnly` (boolean): restrict to your favorited companies; `false` explicitly disables it.
-  - `postedWithinDays`: `0`, `1`, `3`, `7`, `14`, `30`; `0` disables the saved posting window. Uses the backend discovery-date policy; omitted uses saved/default preferences.
-  - `salaryFloorUsd`: integer `0`–`1000000`. Excludes comparable listed annual-USD minimums below this floor. Unknown, hourly and non-USD salaries remain visible; this is not a guaranteed salary threshold. `0` disables the floor; omitted uses saved/default preferences.
-  - `since`: ISO-8601 date or timestamp within the past 90 days, never in the future. Filters when Trackly first saw a job, rather than the employer posting date. Prefer a timestamp with timezone for incremental sync. Other saved filters still apply: use `postedWithinDays:0` and `salaryFloorUsd:0` to disable those saved constraints.
+  - `postedWithinDays`: `0`, `1`, `3`, `7`, `14`, `30`; `0` disables the saved posting window. Uses the backend discovery-date policy; omitted uses saved/default preferences only with status omitted, `new`, or `all`. Explicit pipeline views (`applied_confirmed`, `check_later`, `not_interested`) skip the saved window/floor; explicit request values still apply.
+  - `salaryFloorUsd`: integer `0`–`1000000`. Excludes comparable listed annual-USD minimums below this floor. Unknown, hourly and non-USD salaries remain visible; this is not a guaranteed salary threshold. `0` disables the floor; omitted uses saved/default preferences only with status omitted, `new`, or `all`. Explicit pipeline views (`applied_confirmed`, `check_later`, `not_interested`) skip the saved window/floor; explicit request values still apply.
+  - `since`: ISO-8601 date or timestamp within the past 90 days, never in the future. Filters when Trackly first saw a job, rather than the employer posting date. Prefer a timestamp with timezone for incremental sync. Since does not reset filters. Saved posting and salary constraints apply only with status omitted, `new`, or `all`; explicit pipeline views skip those saved constraints while retaining explicit request filters: use `postedWithinDays:0` and `salaryFloorUsd:0` to disable those saved constraints.
   - `locationFilter`: compatibility alias; use instead of `region`. Pass ONE of
     - a single scalar: `us`, `non_us`, `all`, or a region tag (`europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`), OR
     - an array of region tags for multi-region (e.g. `["europe", "canada"]`). The array form excludes `us` — combining `us` with other tags in an array causes the backend to silently drop the others. To get "not US" use the scalar `non_us` alone.

package/mcp/analytics.js

@@ -118,6 +118,28 @@ const SAFE_ENUM_KEYS = new Set([
   'region', 'regiontag', 'locationfilter', 'sort', 'sponsorship',
 ]);
 const SDK_FAILURE_WARNING = /Warning: (?:Failed to instrument server|Failed to setup tool call instrumentation|No PostHog client passed)/i;
+const ERROR_CATEGORIES = new Set([
+  'authentication', 'authorization', 'rate_limit', 'timeout', 'not_found',
+  'validation', 'conflict', 'network', 'server', 'unknown',
+]);
+const HTTP_ERROR_CATEGORIES = {
+  400: 'validation', 401: 'authentication', 403: 'authorization',
+  404: 'not_found', 408: 'timeout', 409: 'conflict', 410: 'not_found',
+  413: 'validation', 422: 'validation', 429: 'rate_limit',
+};
+const CLIENT_FAMILIES = [
+  ['chatgpt', /\bchatgpt\b/],
+  ['claude', /\bclaude(?: desktop)?\b/],
+  ['codex', /\bcodex\b/],
+  ['cursor', /\bcursor\b/],
+  ['windsurf', /\bwindsurf\b/],
+  ['vscode', /\b(?:vscode|visual studio code)\b/],
+  ['continue', /\bcontinue\b/],
+  ['cline', /\bcline\b/],
+  ['roo', /\broo(?: code)?\b/],
+  ['zed', /\bzed\b/],
+  ['mcp-inspector', /\bmcp inspector\b/],
+];
 
 const ALLOWED_EVENT_PROPERTY_KEYS = new Set([
   '$exception_list', '$lib', '$lib_version', '$mcp_client_name',
@@ -250,6 +272,13 @@ function classifyIntent(toolName, value) {
 
 function classifyError(value) {
   const text = typeof value === 'string' ? value.toLowerCase() : '';
+  if (ERROR_CATEGORIES.has(text)) return text;
+  // HTTP status is authoritative; endpoint words such as "network brief"
+  // must not turn an upstream 500 into a transport/network classification.
+  const status = /\bhttp\s+([45]\d\d)\b/.exec(text)?.[1];
+  if (status && HTTP_ERROR_CATEGORIES[status]) return HTTP_ERROR_CATEGORIES[status];
+  if (status?.startsWith('5')) return 'server';
+  if (status) return 'unknown';
   if (/\b(?:401|unauthenticated|authentication|invalid token|expired token)\b/.test(text)) {
     return 'authentication';
   }
@@ -264,6 +293,38 @@ function classifyError(value) {
   return 'unknown';
 }
 
+function canonicalClientFamily(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 240) return undefined;
+  const normalized = value.toLowerCase().replace(/[_-]/g, ' ');
+  return CLIENT_FAMILIES.find(([, pattern]) => pattern.test(normalized))?.[0];
+}
+
+function projectEventAttribution(properties, eventName) {
+  const clientValues = [
+    properties.$mcp_vendor_client,
+    properties.$mcp_client_name,
+    properties.$mcp_client_user_agent,
+  ];
+  const clientFamily = clientValues.map(canonicalClientFamily).find(Boolean)
+    || (clientValues.some((value) => (
+      typeof value === 'string' && value.trim() && value !== 'unknown'
+    )) ? 'other' : 'unknown');
+  properties.$mcp_vendor_client = clientFamily;
+  properties.$mcp_client_name = clientFamily;
+  if (properties.$mcp_client_user_agent !== undefined) {
+    properties.$mcp_client_user_agent = canonicalClientFamily(properties.$mcp_client_user_agent)
+      || 'other';
+  }
+
+  const errorMessage = properties.$mcp_error_message;
+  const exceptionMessage = properties.$exception_list?.[0]?.value;
+  const isError = eventName === '$exception' || properties.$mcp_is_error === true;
+  properties.$mcp_error_type = isError
+    ? classifyError(errorMessage ?? exceptionMessage ?? properties.$mcp_error_type)
+    : 'none';
+  return errorMessage;
+}
+
 function safeFrameName(value, maxLength = 120) {
   if (typeof value !== 'string' || value === '<local-path>') return undefined;
   const basename = value.replace(/\\/g, '/').split('/').pop() || '';
@@ -311,7 +372,7 @@ function projectExceptionList(value, errorValue) {
     }).filter((frame) => Object.keys(frame).length > 0);
     return {
       type: safeFrameName(exception.type, 80) || 'Error',
-      category: classifyError(exception.value ?? errorValue),
+      category: classifyError(exception.category ?? exception.value ?? errorValue),
       stacktrace: { frames: projectedFrames },
     };
   });
@@ -521,6 +582,7 @@ function sanitizeMcpAnalyticsEvent(event) {
   }
   const properties = sanitized.properties;
   if (!properties || typeof properties !== 'object') return sanitized;
+  const sourceErrorMessage = projectEventAttribution(properties, event.event);
 
   // Identity is backend-owned. The CLI may carry only its ephemeral anonymous
   // session identifier; verified user/person properties never cross this relay.
@@ -582,7 +644,6 @@ function sanitizeMcpAnalyticsEvent(event) {
     delete properties.$mcp_intent_source;
   }
 
-  const sourceErrorMessage = properties.$mcp_error_message;
   if (typeof sourceErrorMessage === 'string') {
     properties.$mcp_error_message = classifyError(sourceErrorMessage);
   }

package/mcp/server.js

@@ -232,9 +232,13 @@ function wrapTool(handler, fallbackMessage) {
       };
     } catch (error) {
       if (extra && typeof extra === 'object') {
+        const statusPrefix = Number.isInteger(error?.status) ? `HTTP ${error.status}: ` : '';
         extra.__mcp_analytics_error = error instanceof Error
           ? error
-          : new Error(error?.message || fallbackMessage, { cause: error });
+          : new Error(
+            `${statusPrefix}${error?.error || error?.message || fallbackMessage}`,
+            { cause: error },
+          );
       }
       return createErrorResult(
         error,
@@ -274,9 +278,9 @@ function createServer() {
       caProvinces: z.array(z.enum(CA_PROVINCES)).min(1).max(14).optional().describe('Canadian province/territory codes or REMOTE. Multiple values select alternatives. REMOTE alongside codes also includes remote jobs. Parent-scoped OR requires canonical location enforcement. Do not combine with remote=true.'),
       internshipLevels: z.array(z.enum(INTERNSHIP_LEVELS)).min(1).max(4).optional().describe('Internship education levels, combined with OR: undergraduate, graduate, mba, not_specified. Applies to internships in jobModality=internship or all; full-time jobs remain unaffected. This does not change the saved/default modality: set jobModality explicitly when you want internships.'),
       favoriteCompaniesOnly: z.boolean().optional().describe('true limits results to your favorited companies; false explicitly disables this restriction.'),
-      postedWithinDays: z.union([z.literal(0), z.literal(1), z.literal(3), z.literal(7), z.literal(14), z.literal(30)]).optional().describe('Posting-recency window in days: 1, 3, 7, 14, or 30; 0 disables the saved window. Uses the backend discovery-date policy; not an incremental-sync cursor. Omit to use the saved/default window.'),
-      salaryFloorUsd: z.number().int().min(0).max(1_000_000).optional().describe('Annual USD minimum salary floor. Excludes comparable listed annual-USD minimums below this amount; unknown, hourly and non-USD salaries remain visible. 0 disables the floor; omitted uses saved/default preferences. This is not a guaranteed salary threshold.'),
-      since: z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/).optional().describe('Incremental sync: jobs first seen by Trackly since this ISO-8601 date/timestamp, not employer posting dates. Must be within the past 90 days and not in the future; backend validates the range. Prefer a timestamp with timezone. Other saved filters still apply; use postedWithinDays=0 and salaryFloorUsd=0 to disable those saved constraints.'),
+      postedWithinDays: z.union([z.literal(0), z.literal(1), z.literal(3), z.literal(7), z.literal(14), z.literal(30)]).optional().describe('Posting-recency window in days: 1, 3, 7, 14, or 30; 0 disables the saved window. Uses the backend discovery-date policy; not an incremental-sync cursor. Omitted uses the saved/default window only when status is omitted, new, or all; explicit pipeline statuses skip that saved window. Explicit values apply in every view.'),
+      salaryFloorUsd: z.number().int().min(0).max(1_000_000).optional().describe('Annual USD minimum salary floor. Excludes comparable listed annual-USD minimums below this amount; unknown, hourly and non-USD salaries remain visible. 0 disables the floor. Omitted uses saved/default preferences only when status is omitted, new, or all; explicit pipeline statuses skip the saved floor. Explicit values apply in every view. This is not a guaranteed salary threshold.'),
+      since: z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/).optional().describe('Incremental sync: jobs first seen by Trackly since this ISO-8601 date/timestamp, not employer posting dates. Must be within the past 90 days and not in the future; backend validates the range. Prefer a timestamp with timezone. Since does not reset filters. Saved posting and salary constraints apply only when status is omitted, new, or all; use postedWithinDays=0 and salaryFloorUsd=0 to disable them. Explicit pipeline views skip saved filters; explicit request filters still apply.'),
       locationFilter: z.union([
         z.enum(['us', 'non_us', 'all']),
         z.enum(REGION_TAGS),

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "trackly-cli",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "trackly-cli",
-      "version": "0.21.0",
+      "version": "0.21.2",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.32.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "Search 250K+ jobs across 5,400+ companies with the Trackly CLI and MCP server for Claude, ChatGPT, Codex and Cursor. Filter by role, location, salary and sponsorship; track jobs and prepare applications.",
   "bin": {

package/server.json

@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.21.0",
+  "version": "0.21.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.21.0",
+      "version": "0.21.2",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {