jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/session/types.d.ts

@@ -0,0 +1,80 @@
+import type { BrowserFingerprintWithHeaders } from 'fingerprint-generator';
+import type { FingerprintConfigJson } from '../browser-process/anti-detect-config.js';
+import type { ResolvedLocale } from '../fingerprinting/locale-resolver.js';
+import type { Cookie } from '../page.js';
+export declare const SCHEMA_VERSION: 1;
+/**
+ * Snapshot of launch-time inputs that saveSession() needs to read off a CdpPage
+ * to assemble a bundle. Populated by CDPBrowserController before handing the
+ * page to user code, so saveSession is a pure call against the page surface.
+ */
+export interface LaunchSnapshot {
+    fingerprintConfig?: FingerprintConfigJson;
+    fingerprintOptions?: Record<string, unknown>;
+    resolvedLocale?: ResolvedLocale;
+    fingerprint?: BrowserFingerprintWithHeaders;
+    userDataDir?: string;
+    proxyUrl?: string;
+    /** Set when the page was launched from a previously-saved bundle. */
+    sessionBundle?: SessionBundle;
+}
+/**
+ * Cookie shape as accepted by CDP `Network.setCookie`. Aliased to the Cookie
+ * already used across CdpPage so save/restore round-trips byte-for-byte.
+ */
+export type SerializedCookie = Cookie;
+/** Origin → key-value map for localStorage / sessionStorage. */
+export type StorageMap = Record<string, Record<string, string>>;
+export interface SessionBundleUserDataDir {
+    encoding: 'base64+gzip+tar';
+    bytes: string;
+    sizeBytes: number;
+    capturedFiles: number;
+}
+export interface SessionBundleBrowserProfile {
+    userAgent: string;
+    platform: string;
+    language: string;
+    screenWidth: number;
+    screenHeight: number;
+    devicePixelRatio: number;
+    webglRenderer: string;
+    webglVendor: string;
+}
+export interface SessionBundleFingerprintInput {
+    locale?: string;
+    languages?: string;
+    timezone?: string;
+    platform?: string;
+    seedKey?: string;
+    /** Pinned on restore so the captured fingerprintConfig is not regenerated. */
+    useNonApifyFingerprints: false;
+    /** Any other fingerprintOptions keys carried through verbatim. */
+    [key: string]: unknown;
+}
+export interface SessionBundleProxyMeta {
+    proxyUrl?: string;
+    sessionId?: string;
+    countryCode?: string;
+}
+export interface SessionBundle {
+    schemaVersion: typeof SCHEMA_VERSION;
+    createdAt: string;
+    createdBy?: {
+        package: 'cdp-crawler';
+        version: string;
+    };
+    cookies: SerializedCookie[];
+    localStorage: StorageMap;
+    sessionStorage: StorageMap;
+    userDataDir: SessionBundleUserDataDir | null;
+    fingerprintConfig: FingerprintConfigJson;
+    fingerprint: BrowserFingerprintWithHeaders;
+    fingerprintInput: SessionBundleFingerprintInput;
+    resolvedLocale: ResolvedLocale;
+    browserProfile: SessionBundleBrowserProfile;
+    proxyMeta?: SessionBundleProxyMeta;
+}
+/** Runtime guard so a hand-edited / partial bundle fails fast with a clear message. */
+export declare function assertValidBundle(value: unknown): asserts value is SessionBundle;
+//# sourceMappingURL=types.d.ts.map

package/dist/session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"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"}

package/dist/session/types.js

@@ -0,0 +1,29 @@
+export const SCHEMA_VERSION = 1;
+/** Runtime guard so a hand-edited / partial bundle fails fast with a clear message. */
+export function assertValidBundle(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Invalid session bundle: expected an object');
+    }
+    const b = value;
+    if (b.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error(`Unsupported session bundle schemaVersion: ${String(b.schemaVersion)} (expected ${SCHEMA_VERSION})`);
+    }
+    for (const key of ['cookies', 'localStorage', 'sessionStorage', 'fingerprintConfig', 'fingerprint', 'fingerprintInput', 'resolvedLocale', 'browserProfile']) {
+        if (b[key] === undefined || b[key] === null) {
+            throw new Error(`Invalid session bundle: missing required key "${key}"`);
+        }
+    }
+    if (!Array.isArray(b.cookies)) {
+        throw new Error('Invalid session bundle: "cookies" must be an array');
+    }
+    if (b.userDataDir !== null && typeof b.userDataDir !== 'object') {
+        throw new Error('Invalid session bundle: "userDataDir" must be an object or null');
+    }
+    if (b.userDataDir) {
+        const u = b.userDataDir;
+        if (u.encoding !== 'base64+gzip+tar' || typeof u.bytes !== 'string') {
+            throw new Error('Invalid session bundle: malformed userDataDir payload');
+        }
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAU,CAAC;AAoFzC,uFAAuF;AACvF,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,aAAa,KAAK,cAAc,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACX,6CAA6C,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,cAAc,GAAG,CACtG,CAAC;IACN,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,CAAU,EAAE,CAAC;QACnK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,iDAAiD,GAAG,GAAG,CAAC,CAAC;QAC7E,CAAC;IACL,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,GAAG,CAAC,CAAC,WAAsC,CAAC;QACnD,IAAI,CAAC,CAAC,QAAQ,KAAK,iBAAiB,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC7E,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/session-profile.d.ts

@@ -0,0 +1,102 @@
+/**
+ * SessionProfile - the single home for session-identity resolution.
+ *
+ * A session's identity (which fingerprint profile it gets, whether the C++
+ * anti-detect binary handles spoofing, which OS family it claims) is derived
+ * from the same few inputs everywhere: the proxy URL's `session-X` token, the
+ * caller's fingerprintOptions, and the host OS. These rules used to be
+ * copy-pasted across browser-plugin.ts, browser-controller.ts, and
+ * fingerprint-injector.ts; they live here now so a change to any rule is a
+ * one-file edit and each priority chain is unit-testable in isolation.
+ */
+export type OsHint = 'macos' | 'linux' | 'windows';
+export type NavigatorPlatform = 'Win32' | 'MacIntel' | 'Linux x86_64';
+/**
+ * Extract the `session-X` token from an Apify proxy URL
+ * (e.g. http://groups-RESIDENTIAL,session-abc123:pw@proxy.apify.com:8000 → "abc123").
+ */
+export declare function extractProxySessionId(proxyUrl: string | null | undefined): string | null;
+/**
+ * Seed source for deterministic fingerprint-profile selection.
+ *
+ * Production path: the proxy URL's `session-X` token, so each Apify session
+ * sticks to one profile across retries. Test/A-B path (no proxy at all):
+ * `fingerprintOptions.seedKey`, so harvest comparisons across hosts (Mac vs
+ * Linux Docker) hit the SAME bundled profile without needing a fake proxy.
+ *
+ * Note the asymmetry, preserved from the original call sites: when a proxy URL
+ * is present but carries no session token, the result is null - the explicit
+ * seedKey is only consulted when there is no proxy.
+ */
+export declare function resolveSeedKey(input: {
+    proxyUrl?: string | null;
+    explicitSeedKey?: unknown;
+}): string | null;
+/**
+ * Seed key for the JS injection bundle's `__stealth.seedKey` store.
+ * Differs from {@link resolveSeedKey}: when the proxy URL carries no
+ * `session-X` token, the full proxy URL itself is the seed (still stable per
+ * session for session-pinned proxies), and an unparseable URL falls back the
+ * same way. No proxy → null.
+ */
+export declare function resolveInjectionSeedKey(proxyUrl: string | null | undefined): string | null;
+/**
+ * Resolve the fingerprint-enforcement engine to a boolean "is native stealth"
+ * (issue #80). The canonical selector is `launchOptions.stealth.engine`; when
+ * set it is authoritative (explicit `'js'` forces the JS path even if a legacy
+ * flag lingers). Otherwise fall back to the legacy `useNativeStealth` locations
+ * (any truthy source wins):
+ *   1. Top-level launchOptions (e.g. CDPBrowserPlugin constructor arg)
+ *   2. Inside launchOptions.fingerprintOptions (e.g. datadome test / crawler launchOptions)
+ *   3. At launchContext root (some CDPCrawler launchContext configurations)
+ */
+export declare function resolveUseNativeStealth(launchOptions: {
+    stealth?: {
+        engine?: unknown;
+    };
+    useNativeStealth?: unknown;
+    fingerprintOptions?: {
+        useNativeStealth?: unknown;
+    };
+} | undefined, launchContextRoot?: {
+    useNativeStealth?: unknown;
+}): boolean;
+/** Map a navigator.platform value onto its OS family. */
+export declare function platformToOsHint(platform: NavigatorPlatform | undefined): OsHint | undefined;
+/** Map an OS family onto its canonical navigator.platform value. */
+export declare function osHintToPlatform(os: OsHint): NavigatorPlatform;
+/** Map a Node `process.platform` onto an OS family (null for exotic hosts). */
+export declare function hostPlatformToOsHint(hostPlatform: NodeJS.Platform): OsHint | null;
+/**
+ * Map a Chrome User-Agent string onto its OS family via the UA OS token.
+ *
+ * This is the authoritative OS signal for a fingerprint: Chrome's UA OS token
+ * (and the parallel `userAgentData.platform`) is far harder for the upstream
+ * pool to contaminate than `navigator.platform`. The pool ships a recurring
+ * ~2.5% of "windows" draws whose UA + uaData say Windows but whose
+ * `navigator.platform` lies "Linux x86_64" - trusting the UA here rather than
+ * the platform field keeps OS resolution on the coherent majority signal.
+ */
+export declare function osHintFromUserAgent(userAgent: string | undefined): OsHint | undefined;
+/**
+ * The OS family a session claims. Priority chain (first hit wins):
+ *   1. operatingSystems[0] from fingerprintGeneratorOptions - the single source
+ *      of truth for OS selection (issue #80)
+ *   2. Explicit user platform pin (the deprecated fingerprintOptions.platform).
+ *      When it contradicts #1, #1 wins; callers warn via `describeOsConflict`.
+ *   3. The existing fingerprint's UA OS token (Crawlee-generated). UA-first
+ *      because `navigator.platform` is the field the upstream pool contaminates
+ *      (Windows UA + "Linux x86_64" platform); the UA is the coherent signal.
+ *   4. The existing fingerprint's navigator.platform string - fallback when the
+ *      UA carried no recognisable OS token.
+ *   5. Host OS (null on exotic hosts - callers that need a hard default
+ *      apply their own, e.g. `?? 'windows'`)
+ */
+export declare function resolveOsHint(input: {
+    explicitPlatform?: NavigatorPlatform;
+    operatingSystems?: string[];
+    fingerprintUserAgent?: string;
+    fingerprintPlatform?: string;
+    hostPlatform?: NodeJS.Platform;
+}): OsHint | null;
+//# sourceMappingURL=session-profile.d.ts.map

package/dist/session-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-profile.d.ts","sourceRoot":"","sources":["../src/session-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AACnD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;AAUtE;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,MAAM,GAAG,IAAI,CAKhB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACnC,aAAa,EAAE;IACX,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACvD,GAAG,SAAS,EACb,iBAAiB,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACnD,OAAO,CAOT;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK5F;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAI9D;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,GAAG,IAAI,CAKjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASrF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACjC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAClC,GAAG,MAAM,GAAG,IAAI,CAkBhB"}

package/dist/session-profile.js

@@ -0,0 +1,163 @@
+/**
+ * SessionProfile - the single home for session-identity resolution.
+ *
+ * A session's identity (which fingerprint profile it gets, whether the C++
+ * anti-detect binary handles spoofing, which OS family it claims) is derived
+ * from the same few inputs everywhere: the proxy URL's `session-X` token, the
+ * caller's fingerprintOptions, and the host OS. These rules used to be
+ * copy-pasted across browser-plugin.ts, browser-controller.ts, and
+ * fingerprint-injector.ts; they live here now so a change to any rule is a
+ * one-file edit and each priority chain is unit-testable in isolation.
+ */
+// `:` and `@` are excluded so a match against a full proxy URL stops at the
+// credential delimiters. The historical plugin/controller variant of this
+// regex was `/session-([^,&]+)/i` run against the FULL URL, which greedily
+// captured "abc123:pw@proxy.apify.com:8000" - the password leaked into the
+// seed material AND the seed disagreed with the injector's variant (which
+// matched only the URL username and got "abc123"). One regex, one answer now.
+const SESSION_TOKEN_RE = /session-([^,&:@]+)/i;
+/**
+ * Extract the `session-X` token from an Apify proxy URL
+ * (e.g. http://groups-RESIDENTIAL,session-abc123:pw@proxy.apify.com:8000 → "abc123").
+ */
+export function extractProxySessionId(proxyUrl) {
+    if (!proxyUrl)
+        return null;
+    return proxyUrl.match(SESSION_TOKEN_RE)?.[1] ?? null;
+}
+/**
+ * Seed source for deterministic fingerprint-profile selection.
+ *
+ * Production path: the proxy URL's `session-X` token, so each Apify session
+ * sticks to one profile across retries. Test/A-B path (no proxy at all):
+ * `fingerprintOptions.seedKey`, so harvest comparisons across hosts (Mac vs
+ * Linux Docker) hit the SAME bundled profile without needing a fake proxy.
+ *
+ * Note the asymmetry, preserved from the original call sites: when a proxy URL
+ * is present but carries no session token, the result is null - the explicit
+ * seedKey is only consulted when there is no proxy.
+ */
+export function resolveSeedKey(input) {
+    if (input.proxyUrl) {
+        return extractProxySessionId(input.proxyUrl);
+    }
+    return typeof input.explicitSeedKey === 'string' ? input.explicitSeedKey : null;
+}
+/**
+ * Seed key for the JS injection bundle's `__stealth.seedKey` store.
+ * Differs from {@link resolveSeedKey}: when the proxy URL carries no
+ * `session-X` token, the full proxy URL itself is the seed (still stable per
+ * session for session-pinned proxies), and an unparseable URL falls back the
+ * same way. No proxy → null.
+ */
+export function resolveInjectionSeedKey(proxyUrl) {
+    if (!proxyUrl)
+        return null;
+    return extractProxySessionId(proxyUrl) ?? proxyUrl;
+}
+/**
+ * Resolve the fingerprint-enforcement engine to a boolean "is native stealth"
+ * (issue #80). The canonical selector is `launchOptions.stealth.engine`; when
+ * set it is authoritative (explicit `'js'` forces the JS path even if a legacy
+ * flag lingers). Otherwise fall back to the legacy `useNativeStealth` locations
+ * (any truthy source wins):
+ *   1. Top-level launchOptions (e.g. CDPBrowserPlugin constructor arg)
+ *   2. Inside launchOptions.fingerprintOptions (e.g. datadome test / crawler launchOptions)
+ *   3. At launchContext root (some CDPCrawler launchContext configurations)
+ */
+export function resolveUseNativeStealth(launchOptions, launchContextRoot) {
+    const engine = launchOptions?.stealth?.engine;
+    if (engine === 'native')
+        return true;
+    if (engine === 'js')
+        return false;
+    return !!launchOptions?.useNativeStealth
+        || !!launchOptions?.fingerprintOptions?.useNativeStealth
+        || !!launchContextRoot?.useNativeStealth;
+}
+/** Map a navigator.platform value onto its OS family. */
+export function platformToOsHint(platform) {
+    if (platform === 'MacIntel')
+        return 'macos';
+    if (platform === 'Linux x86_64')
+        return 'linux';
+    if (platform === 'Win32')
+        return 'windows';
+    return undefined;
+}
+/** Map an OS family onto its canonical navigator.platform value. */
+export function osHintToPlatform(os) {
+    if (os === 'macos')
+        return 'MacIntel';
+    if (os === 'linux')
+        return 'Linux x86_64';
+    return 'Win32';
+}
+/** Map a Node `process.platform` onto an OS family (null for exotic hosts). */
+export function hostPlatformToOsHint(hostPlatform) {
+    if (hostPlatform === 'darwin')
+        return 'macos';
+    if (hostPlatform === 'linux')
+        return 'linux';
+    if (hostPlatform === 'win32')
+        return 'windows';
+    return null;
+}
+/**
+ * Map a Chrome User-Agent string onto its OS family via the UA OS token.
+ *
+ * This is the authoritative OS signal for a fingerprint: Chrome's UA OS token
+ * (and the parallel `userAgentData.platform`) is far harder for the upstream
+ * pool to contaminate than `navigator.platform`. The pool ships a recurring
+ * ~2.5% of "windows" draws whose UA + uaData say Windows but whose
+ * `navigator.platform` lies "Linux x86_64" - trusting the UA here rather than
+ * the platform field keeps OS resolution on the coherent majority signal.
+ */
+export function osHintFromUserAgent(userAgent) {
+    const ua = userAgent ?? '';
+    // Order matters: a Mac UA carries "Mac OS X"; Windows carries "Windows NT";
+    // Linux carries "X11; Linux" / "Linux x86_64" (excluding Android / CrOS,
+    // which are not desktop-Linux families we target).
+    if (/Macintosh|Mac OS X/i.test(ua))
+        return 'macos';
+    if (/Windows NT/i.test(ua))
+        return 'windows';
+    if (/X11; Linux|Linux x86_64/i.test(ua) && !/Android|CrOS/i.test(ua))
+        return 'linux';
+    return undefined;
+}
+/**
+ * The OS family a session claims. Priority chain (first hit wins):
+ *   1. operatingSystems[0] from fingerprintGeneratorOptions - the single source
+ *      of truth for OS selection (issue #80)
+ *   2. Explicit user platform pin (the deprecated fingerprintOptions.platform).
+ *      When it contradicts #1, #1 wins; callers warn via `describeOsConflict`.
+ *   3. The existing fingerprint's UA OS token (Crawlee-generated). UA-first
+ *      because `navigator.platform` is the field the upstream pool contaminates
+ *      (Windows UA + "Linux x86_64" platform); the UA is the coherent signal.
+ *   4. The existing fingerprint's navigator.platform string - fallback when the
+ *      UA carried no recognisable OS token.
+ *   5. Host OS (null on exotic hosts - callers that need a hard default
+ *      apply their own, e.g. `?? 'windows'`)
+ */
+export function resolveOsHint(input) {
+    const fromOpSys = input.operatingSystems?.[0]?.toLowerCase();
+    if (fromOpSys === 'macos' || fromOpSys === 'linux' || fromOpSys === 'windows') {
+        return fromOpSys;
+    }
+    const fromExplicit = platformToOsHint(input.explicitPlatform);
+    if (fromExplicit)
+        return fromExplicit;
+    const fromUa = osHintFromUserAgent(input.fingerprintUserAgent);
+    if (fromUa)
+        return fromUa;
+    const p = (input.fingerprintPlatform ?? '').toLowerCase();
+    if (p.includes('mac'))
+        return 'macos';
+    if (p.includes('linux'))
+        return 'linux';
+    if (p.includes('win'))
+        return 'windows';
+    return hostPlatformToOsHint(input.hostPlatform ?? process.platform);
+}
+//# sourceMappingURL=session-profile.js.map

package/dist/session-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-profile.js","sourceRoot":"","sources":["../src/session-profile.ts"],"names":[],"mappings":"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"}