trackly-cli 0.15.0 → 0.16.0

package/README.md

@@ -46,6 +46,7 @@ trackly jobs --region us              # Filter by region (us, non_us, all, or a
 trackly jobs --job-type internship    # Filter by employment type (full_time, internship, all)
 trackly jobs --work-arrangement hybrid,remote  # Filter by work arrangement independently
 trackly jobs --function product       # Filter by function
+trackly jobs --sponsorship exclude_no # Visa sponsorship filter (all, exclude_no, only_yes)
 trackly jobs --company 243            # Filter by company ID
 trackly job 1234                      # Get job details
 trackly jobs 1234                     # Alias for job details
@@ -161,7 +162,7 @@ Then use natural language in any of these clients:
 
 | Tool | Description |
 |------|-------------|
-| trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, and status |
+| trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, visa sponsorship, and status |
 | trackly_get_job | Get full details for a specific job |
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |

package/bin/trackly

@@ -39,6 +39,7 @@ const VALUE_FLAGS = new Set([
   'region',
   'search',
   'sort',
+  'sponsorship',
   'status',
   'url',
   'window-days',
@@ -62,7 +63,7 @@ const COMMAND_FLAGS = {
   login: [],
   logout: [],
   whoami: [],
-  jobs: ['function', 'company', 'region', 'job-type', 'work-arrangement', 'remote', 'status', 'sort', 'limit', 'offset', 'keywords', 'location', 'modality'],
+  jobs: ['function', 'company', 'region', 'job-type', 'work-arrangement', 'remote', 'status', 'sort', 'sponsorship', 'limit', 'offset', 'keywords', 'location', 'modality'],
   job: [],
   companies: ['limit', 'offset'],
   search: [],
@@ -94,6 +95,15 @@ const STATUS_LABELS = {
   dismissed: 'dismissed',
 };
 const WORK_ARRANGEMENT_VALUES = ['remote', 'hybrid', 'in_person', 'unspecified'];
+// Discovery-only visa sponsorship filter (close-ai PR #1578). Mirrors the
+// hosted MCP enum exactly. Absent or 'all' applies no filter.
+const SPONSORSHIP_VALUES = ['all', 'exclude_no', 'only_yes'];
+// Job-detail `sponsorshipStatus` values → user-facing copy. Anything else
+// (including null/'unknown') reads "Not mentioned" — never "unknown".
+const SPONSORSHIP_STATUS_LABELS = {
+  yes: 'Sponsors visa',
+  no: 'No sponsorship',
+};
 const JOB_FUNCTIONS = [
   'product', 'engineering', 'design', 'data', 'marketing', 'sales', 'partnerships',
   'finance', 'strategy', 'operations', 'people', 'legal', 'support', 'other',
@@ -324,7 +334,7 @@ function hasJobListFilters(args) {
   // (which then raises the migration error) instead of cmdJob(42) silently ignoring
   // the filter. See PR #13 Cursor Bugbot finding.
   const deprecated = Object.keys(DEPRECATED_JOB_FLAGS);
-  const active = ['function', 'company', 'keywords', 'limit', 'region', 'job-type', 'work-arrangement', 'remote', 'offset', 'sort', 'status'];
+  const active = ['function', 'company', 'keywords', 'limit', 'region', 'job-type', 'work-arrangement', 'remote', 'offset', 'sort', 'sponsorship', 'status'];
   return [...active, ...deprecated].some((key) => args[key] !== undefined);
 }
 
@@ -598,6 +608,17 @@ async function cmdJobs(args) {
     }
   }
 
+  let sponsorship;
+  if (args.sponsorship !== undefined) {
+    if (typeof args.sponsorship !== 'string' || !args.sponsorship.trim()) {
+      failNow(`--sponsorship requires a value. Use: ${SPONSORSHIP_VALUES.join(', ')}.`);
+    }
+    sponsorship = args.sponsorship.trim();
+    if (!SPONSORSHIP_VALUES.includes(sponsorship)) {
+      failNow(`Invalid --sponsorship value "${sponsorship}". Use: ${SPONSORSHIP_VALUES.join(', ')}.`);
+    }
+  }
+
   const params = new URLSearchParams();
   if (args.function) params.set('jobFunction', args.function);
   if (args.company) params.set('companyId', args.company);
@@ -607,6 +628,13 @@ async function cmdJobs(args) {
   if (args.remote) params.set('usStates', 'REMOTE');
   if (args.status) params.set('status', args.status);
   if (args.sort) params.set('sort', args.sort);
+  if (sponsorship) {
+    params.set('sponsorship', sponsorship);
+    // The backend honors the filter only on the literal status=new discovery
+    // view — without this default, `--sponsorship exclude_no` alone would be
+    // a silent no-op. Mirrors the MCP server's behavior.
+    if (sponsorship !== 'all' && !args.status) params.set('status', 'new');
+  }
   if (args.limit) params.set('limit', args.limit);
   if (args.offset) params.set('offset', args.offset);
   if (args.keywords) params.set('search', args.keywords);
@@ -638,6 +666,12 @@ async function cmdJob(args) {
     if (job.location) console.log(`Location: ${job.location}`);
     if (job.jobUrl) console.log(`URL: ${color('dim', job.jobUrl)}`);
     if (job.postedAt) console.log(`Posted: ${job.postedAt}`);
+    // Field presence, not truthiness: a returned null/'unknown' status is a real
+    // "Not mentioned" answer from the backend. Only an older backend that omits
+    // the key entirely should render no Sponsorship line at all.
+    if (job && typeof job === 'object' && 'sponsorshipStatus' in job) {
+      console.log(`Sponsorship: ${SPONSORSHIP_STATUS_LABELS[job.sponsorshipStatus] || 'Not mentioned'}`);
+    }
     if (typeof job.description === 'string' && job.description.length > 0) {
       console.log();
       console.log(color('bold', 'Description:'));
@@ -1277,7 +1311,7 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'login')}                Authenticate via Google OAuth
   ${color('cyan', 'logout')}               Clear credentials
   ${color('cyan', 'whoami')}               Show current user
-  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --region <tag>, --job-type <type>, --work-arrangement <values>, --remote, --status, --sort, --limit, --offset, --keywords)
+  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --region <tag>, --job-type <type>, --work-arrangement <values>, --remote, --status, --sort, --sponsorship, --limit, --offset, --keywords)
   ${color('cyan', 'job <id>')}             Get full job detail
   ${color('cyan', 'jobs <id>')}            Alias for job <id>
   ${color('cyan', 'companies')}            List companies
@@ -1333,6 +1367,10 @@ ${color('bold', 'Filter values:')}
   --status         new, applied_confirmed, check_later, not_interested, all
                    (filters by YOUR application pipeline state)
   --sort           newest (default), match (highest match score first, requires resume)
+  --sponsorship    all (default), exclude_no, only_yes
+                   exclude_no hides jobs that explicitly state they do not sponsor
+                   (~13% of active US jobs); only_yes keeps only jobs that explicitly
+                   state they sponsor (~2%). Most postings never state a policy.
 
 ${color('bold', 'MCP Setup:')}
   Claude Code: claude mcp add --scope user trackly -- trackly mcp

package/docs/trackly-tools.md

@@ -83,6 +83,7 @@ API-key creation attempts.
   - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`.
   - `status`: your application pipeline state. Values: `new`, `applied_confirmed`, `check_later`, `not_interested`, `all`.
   - `sort`: `newest` (default) or `match` (highest match score first; requires a resume on file). Backend rejects the deprecated values `oldest` and `company` with HTTP 400.
+  - `sponsorship`: `all` (default), `exclude_no`, `only_yes`. `exclude_no` hides jobs with a reliable explicit "does not sponsor" statement (~13% of active US jobs); `only_yes` keeps only jobs with a reliable explicit "sponsors" statement (~2%). Most postings never state a policy either way, so `only_yes` is a very narrow slice.
   - `keywords`, `companyId`, `limit`, `offset`.
 - **trackly_get_job** — Get full job details by ID
 - **trackly_search_companies** — Semantic company search

package/mcp/analytics.js

@@ -111,11 +111,11 @@ const SAFE_ENUM_VALUES = new Set([
   'unspecified', 'us', 'non_us', 'europe', 'latam', 'middle_east', 'asia', 'africa',
   'canada', 'oceania', 'unknown', 'product', 'engineering', 'design', 'data',
   'marketing', 'sales', 'partnerships', 'finance', 'strategy', 'operations', 'people',
-  'legal', 'support', 'other', 'newest', 'match',
+  'legal', 'support', 'other', 'newest', 'match', 'exclude_no', 'only_yes',
 ]);
 const SAFE_ENUM_KEYS = new Set([
   'status', 'stage', 'function', 'jobfunction', 'jobmodality', 'workarrangement',
-  'region', 'regiontag', 'locationfilter', 'sort',
+  '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;
 
@@ -474,7 +474,7 @@ function projectMcpParameters(toolName, parameters) {
   const allowed = {
     trackly_search_jobs: new Set([
       'function', 'companyId', 'locationFilter', 'jobModality', 'workArrangements',
-      'remote', 'status', 'sort', 'limit', 'offset', 'keywords',
+      'remote', 'status', 'sort', 'sponsorship', 'limit', 'offset', 'keywords',
     ]),
     trackly_get_job: new Set(['id']),
     trackly_search_companies: new Set(['query', 'limit']),

package/mcp/server.js

@@ -67,6 +67,12 @@ const MCP_MISSING_DESTINATION_VALUES = [
   'trackly', 'external_site', 'file', 'email', 'calendar', 'crm', 'browser', 'other',
 ];
 
+// `sponsorship` enum matches the backend's discovery-only filter (close-ai
+// PR #1578). Absent or 'all' applies no filter; only ~2% of active US jobs
+// carry an explicit "sponsors" statement and ~13% an explicit "does not
+// sponsor" one, so the remaining ~85% never state a policy either way.
+const SPONSORSHIP_VALUES = ['all', 'exclude_no', 'only_yes'];
+
 // `sort` enum matches backend handler at `jobscout.ts:3053` — NOT the pre-fix
 // `newest|oldest|company` (backend rejects oldest/company with HTTP 400).
 const SORT_VALUES = ['newest', 'match'];
@@ -254,6 +260,9 @@ function createServer() {
         'Filter by YOUR application pipeline state. Not a generic job-posting status. Values: ' + STATUS_VALUES.join(', ')
       ),
       sort: z.enum(SORT_VALUES).optional().describe('Sort order: newest (default) or match (highest match score first; requires resume). Backend rejects legacy oldest/company with HTTP 400.'),
+      sponsorship: z.enum(SPONSORSHIP_VALUES).optional().describe(
+        "Visa sponsorship filter. 'exclude_no' hides jobs with a reliable explicit \"does not sponsor\" statement (~13% of active US jobs); 'only_yes' keeps only jobs with a reliable explicit \"sponsors\" statement (~2% — most postings never state a policy either way). Default 'all' shows every job. Applies only to the discovery view: when you pass a filtering mode without `status`, status defaults to 'new' (the backend ignores the filter on tracked/pipeline views)."
+      ),
       limit: z.number().max(50).optional().describe('Max results (default 20, max 50)'),
       offset: z.number().min(0).optional().describe('Pagination offset'),
       keywords: z.string().max(500).optional().describe('Keyword search in title, company, or description'),
@@ -281,6 +290,16 @@ function createServer() {
       if (params.remote === true) qs.set('usStates', 'REMOTE');
       if (params.status !== undefined) qs.set('status', params.status);
       if (params.sort !== undefined) qs.set('sort', params.sort);
+      if (params.sponsorship !== undefined) {
+        qs.set('sponsorship', String(params.sponsorship));
+        // The backend applies the filter only on the literal status=new
+        // discovery view; without this default an agent passing a filtering
+        // mode alone would get silently unfiltered results. Mirrors
+        // close-ai src/mcp/server.ts.
+        if (params.sponsorship !== 'all' && params.status === undefined) {
+          qs.set('status', 'new');
+        }
+      }
       if (params.limit !== undefined) qs.set('limit', String(params.limit));
       if (params.offset !== undefined) qs.set('offset', String(params.offset));
       if (params.keywords !== undefined) qs.set('search', params.keywords);

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "AI job search CLI + hosted MCP server with OAuth. 170K+ jobs, 3,800+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {

package/server.json

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