@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 and fetchers for Greenhouse, Lever, Ashby, Workday, Rippling | | /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 |

Built by Mamba Labs