@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/[email protected]

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 | | /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 |

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.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