@mambalabsdev/gtm-core

@mambalabsdev/gtm-core

Shared runtime for the Mamba Labs GTM actor fleet. Domain and slug normalization, output validation, free-tier metering, HTTP and SERP layers, LinkedIn and social resolution, ATS scrapers, employer resolution, and the merge and provenance engine.

Fourteen actors carried their own copy of most of this. 81 symbol names appeared in two or more actors, 33 of them byte-identical and 48 divergent. This package is the one copy.

Install

npm install @mambalabsdev/gtm-core@0.1.0

Pin an exact version. No carets. A package publish must not be able to reach every actor on its next build.

Use

Import by subpath so an actor pulls in only what it uses:

// CommonJS actors
const { cleanDomain } = require('@mambalabsdev/gtm-core/domain');

// ESM actors
import { toBool } from '@mambalabsdev/gtm-core/coerce';

The package is CommonJS on purpose. Eleven fleet actors are ESM and three are CommonJS; Node's named-export detection for CommonJS serves both natively from one build, with no dual-package hazard and no build step.

Modules

Subpath	What it owns
/coerce	toBool, toInt, toBoundedInt, toStringArray, currentMonthKey, sleep, unique, withTimeout, mapWithConcurrency, safePreview
/output	makeValidator(fields) producing validate, coerce and buildEmptyRecord
/domain	cleanDomain, stripTld, domainToSlug(Candidates), levenshtein, slugCloselyMatches, normalizeName, namesMatch, normalizeLinkedIn, isAggregatorDomain, isJobAggregatorDomain, isAtsHostDomain, hostFromUrl
/metering	createMeter, free-tier gate, monthly usage, fail-open named-KVS wrapper, cross-run cache, charge-on-output
/proxy	buildResidentialProxy, buildDatacenterProxy, proxyUrlGetter, maskProxyUrl
/http	fetchPage, headPage, getJson, postJson
/serp	duckDuckGoSearch, braveSearch, parseResultBlocks, provider registry, resolveApiKey
/social	platform regexes and extract*Url for LinkedIn, Facebook, Instagram, X, YouTube
/linkedin	validateLinkedInUrl, resolveByPatternMatch, resolveWithMethod
/jsonld	findOrganizationNode (subtypes included), parseLdBlocks(Detailed), collectSameAs, formatHqLocation, companyNameFromPage
/schema-org	organizationDepth, isOrganizationNode, the Organization subtype hierarchy as a child-to-parent map
/phone	extractCompanyPhone, normalizePhone, resolveCountry, organizationDepth, company main line scanned from every JSON-LD block on a page, Organization subtypes included; findCompanyMainLine widens it to the contact page, the about page and a search lookup through an injected fetcher and search function
/ats	detectATS, discoverBoard (override, then slug variants, then probe), deriveSlugVariants, and fetchers for Greenhouse, Lever, Ashby, Workday, Rippling. Pass withContent: true to keep job bodies
/render-mode	computeRenderMode(pages) and the exported ratio thresholds plus READABILITY_FLOOR_CHARS
/sensitive-terms	PROTECTED_CHARACTERISTIC_PATTERN, scrubEvidencePhrase(phrase, maxChars)
/provenance	runSource, mergeSources, field, flattenProvenance
/employer	resolveEmployer, employer extraction from a job description
/employment	resolveEmployment, current employer and title from a HeyReach lead's experiences (current, between roles, or unknown), monthYearLabel

Three rules the package keeps

No apify import, anywhere. The two runtime-coupled modules take their runtime surface as an argument:

const meter = await createMeter(
  { openStore: (n) => Actor.openKeyValueStore(n), charge: Actor.charge, setStatus: Actor.setStatusMessage, log },
  { limit: FREE_TIER.ASSISTED, usageStoreName: 'my-actor-usage', cacheStoreName: 'my-actor-cache' },
);

That is what makes the metering code, which is exactly the code Apify's QA gate exercises under a restricted token, testable under plain node --test.

No vendor credential is ever read from the environment. Different clients supply different keys for the same provider, so resolveApiKey(provider, keys, env) takes an explicit key bag, and env defaults to an empty object. An actor that wants an environment fallback passes process.env in itself.

Every named key-value store open is fail-open. Apify's Store QA runs prefill under a LIMITED_PERMISSIONS token that 403s on named-store getOrCreate. An actor that crashes there is flagged Under Maintenance and pulled from discovery. That bug class took out three actors in June and July 2026.

Free-tier allowances

The fleet's 10 / 15 / 25 / 50 spread tracked neither price nor volume nor cost. FREE_TIER replaces it with three classes based on cost to serve, so a free row costs Mamba Labs roughly the same whichever actor produced it:

Class	Rows per month	Applies to
SELF_SERVE	50	pure HTTP and regex, no vendor spend, no browser
ASSISTED	25	SERP fetches, a headless browser, or many fetches per row
VENDOR	10	a paid third-party API call per row, or a sub-actor fan-out

Tests

npm test

test/fixtures/characterization.json freezes what the fleet did on 2026-08-03, captured directly from the actor repos before any symbol moved. The tests assert gtm-core against that frozen behavior. Where gtm-core deliberately differs, the difference is declared in the test with its reason, and the test asserts the new value. An undeclared difference fails the suite.

Regenerate the capture only when you intend to change the contract:

npm run capture

Defects fixed by the extraction

Three came from the audit and three were found during the characterization capture.

Actor	Defect
gtm-tech-stack-signal-scraper	a null entry in domains[] normalized to the literal string "undefined", which is truthy, survived .filter(Boolean), and launched a Playwright crawl against the domain undefined
gtm-tech-stack-signal-scraper	never stripped paths, so stripe.com/pricing was crawled verbatim as a domain
gtm-signals-aggregator	never lowercased, so Stripe.COM and stripe.com were two different companies to the dedupe key and both were processed
gtm-signals-aggregator	normalizeDomain threw a TypeError on a numeric input, because (raw || '').trim() calls .trim on a number
identity-resolver, social-mapper, linkedin-resolver	validateOutput threw a TypeError on a record carrying an undefined field, inside the push path where nothing caught it, because JSON.stringify(undefined).slice(...) throws
Lever fetcher	the Lever posting API returns HTTP 200 with an empty array for a slug with no public board, so "not on Lever" read as "on Lever with zero openings"; now cross-verified against the public careers page

Changelog

0.3.18, 2026-10-07

New subpath /employment. resolveEmployment({ companyName, companyUrl, position, experiences }) reads a HeyReach lead's experiences and returns the employment status. An experience with a null end is current, and the latest start wins when several are open. No open experience means between roles: current company and title are null, and the most recent role is kept as the last known company, title, and end month (YYYY-MM). Missing or empty experiences returns unknown with HeyReach's own companyName and position kept. HeyReach sends experiences as a JSON string; both the string and an array are accepted. HeyReach fills companyName from the newest role with a company and ignores its end date, so a person on a career break reads as still employed. Shared by the Proofed HeyReach import and the Proofed reply card.

0.3.17, 2026-10-06

phone.findCompanyMainLine reads the main line from the homepage, then the contact page, then the about page, then a search engine response, in that order within each tier: structured data, then tel: links, then a number a visible label names as a phone, then search. The homepage alone filled 6.7 percent of 30 domains on 2026-08-05. The module still opens no connection: the caller passes fetchPage(url) and search(query). A hit on a secondary page names the page in its source (contact_page_tel_link, about_page_jsonld_organization); search hits are search_knowledge_graph, search_place, and search_snippet. A .co.uk, .de or similar domain supplies the country when the caller passes none. extractCompanyPhone and its output shape are unchanged. A consumer that caches the new function's result puts MAIN_LINE_SHAPE_VERSION (2) in its cache key.

0.3.16, 2026-09-17

linkedin.resolveByPatternMatch probes the variant slugs three at a time (VARIANT_BATCH) instead of all at once, stopping at the first hit. With the 0.3.15 candidate list a single Promise.all over 8 variants pushed every HEAD through the residential proxy together and 6 of 8 aborted at the 5 s ceiling on the verification run (europascience.com, run rmpHQtMFk6gOlNa30), which turned a real hit into a search fallback. Pin 0.3.16 with 0.3.15's candidates.

0.3.15, 2026-09-17

domain.domainToSlugCandidates(domain, { companyName }) adds hyphenated and name derived LinkedIn slug candidates after the unchanged frozen block: the slugified company name (orlando-weekly, 411-locals, retro-report, ai-global-media), a dictionary split of a run together stem when no name is passed, the name plus a legal suffix (europa-science-ltd), and the stem joined to a word bearing top level domain (techbuzz.news to techbuzznews). Capped at 12. linkedin.resolveByPatternMatch takes companyName in its options and passes it through. The 2026-09-16 Proofed enrichment review found 25 of 33 company page misses were companies whose slug is one of these forms. New exports companyNameToSlug and segmentStem. 43 dependent actor suites pass against this build; the one failure (public-award-monitor, a prefill assertion on its own input schema) is pre-existing and identical on 0.3.9.

0.3.14, 2026-09-15

Withdraws 0.3.13. linkedin.resolveByPatternMatch is back to the stem first, variants on a miss, 5 s HEAD timeout form. On a 50 domain verification run the 3 s ceiling lost 10 of 25 pattern match hits: a LinkedIn HEAD through residential proxy measures 1.6 to 3.8 s. Pin 0.3.14; 0.3.13 is deprecated on npm.

0.3.13, 2026-09-15, withdrawn

linkedin.resolveByPatternMatch checks every slug candidate at once, each HEAD with a 3 s timeout (PATTERN_HEAD_TIMEOUT_MS, also accepted as the timeout option). It checked the bare stem first with a 5 s timeout and only then the variants, so a stem miss cost 7.2 s before any search started; the phase was 26 percent of domain-to-linkedin-url-resolver run time. Candidate order is still preference order: the stem wins when a variant also validates. resolveWithMethod is unchanged in shape. Pin 0.3.13 on the two resolvers.

0.3.7, 2026-08-10

Closes the last known bare-Partner false positive. A digit after Partner is now blocked: DevX Software Engineer (Partner 16, Partner 18), ASG is a real title carried in the contact-classifier drift oracle, those are internal level bands, and it was still classifying as c_level on 0.3.6.

0.3.7 is the version to pin. 0.3.5 and 0.3.6 are progressively weaker versions of the same fix.

0.3.6, 2026-08-10

Completes the 0.3.5 fix. 0.3.5 keyed the lookbehind on the word immediately before Partner only, which missed Talent Acquisition Partner: the qualifier sits one word back, and six people on premiertalentpartners.com/about carry exactly that title. The lookbehind now allows a single intervening word, with partner ranks (Managing, General, Founding, Senior, Equity, Operating, Venture, Name) exempt so Technology Managing Partner stays C-level. acquisition was added to the qualifier list from the same page.

Use 0.3.6, not 0.3.5. 0.3.5 is a strictly weaker version of the same fix.

0.3.5, 2026-08-10

seniority: Partner is no longer a bare token in the c_level rule. THIS IS A BEHAVIOR CHANGE INSIDE A CLASSIFIER.

\bPartner\b answered "does this text contain the word Partner", not "is this title a partner", so every ... Partner and Partner ... title classified as C-suite. Benefits Partner, HR Business Partner, Channel Partner Manager and Partner Sales Director were all c_level, and team-page-people-extractor is public and filters on seniority_filter: executive, so buyers were served HR business partners in place of executives.

Partner now carries a negative lookbehind for qualifier words and a negative lookahead for the function nouns it modifies, both derived from 3373 real ATS job titles and the people-finder benchmark corpora. Partner, Managing Partner, General Partner, Founding Partner and Senior Partner are unchanged and still c_level.

Consumer impact. Titles previously classified c_level on a bare Partner match now classify differently: other where the title has no other rank, or the rank the rest of the title carries (Partner Sales Director is now director, Channel Partner Manager is now manager). Any consumer that has stored historical seniority values will see a discontinuity at this version, and any count of executives taken before and after this release is not comparable. Rows are not dropped; they move down the ladder, and rows sitting behind seniority_filter: executive will disappear from that filter's output.

No other rule, level, filter or export changed.

Built by Mamba Labs