@hraness/ghostget 0.17.2

package/src/providers/iso-bmff.ts

@@ -0,0 +1,338 @@
+type IsoBox = Readonly<{
+  end: number;
+  payloadStart: number;
+  type: string;
+}>;
+
+type IsoBoxBudget = {
+  remaining: number;
+};
+
+const MAX_REVIEWED_ISO_BOXES = 4_096;
+const ISO_BMFF_UNKNOWN_DURATION_V0 = 0xffff_ffffn;
+const ISO_BMFF_UNKNOWN_DURATION_V1 = 0xffff_ffff_ffff_ffffn;
+const IDENTITY_TRACK_MATRIX = Object.freeze([
+  0x0001_0000,
+  0,
+  0,
+  0,
+  0x0001_0000,
+  0,
+  0,
+  0,
+  0x4000_0000,
+] as const);
+
+function isoBoxType(bytes: Uint8Array, offset: number): string {
+  return String.fromCharCode(
+    bytes[offset] ?? 0,
+    bytes[offset + 1] ?? 0,
+    bytes[offset + 2] ?? 0,
+    bytes[offset + 3] ?? 0,
+  );
+}
+
+function isoBoxes(
+  bytes: Uint8Array,
+  start: number,
+  end: number,
+  label: string,
+  budget: IsoBoxBudget,
+): readonly IsoBox[] {
+  if (
+    !Number.isSafeInteger(start)
+    || !Number.isSafeInteger(end)
+    || start < 0
+    || end > bytes.byteLength
+    || start > end
+  ) throw new Error(`${label} has invalid ISO BMFF bounds`);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const boxes: IsoBox[] = [];
+  let offset = start;
+  while (offset < end) {
+    if (budget.remaining === 0) {
+      throw new Error(`${label} exceeds the reviewed ISO BMFF box-count bound`);
+    }
+    budget.remaining -= 1;
+    if (end - offset < 8) {
+      throw new Error(`${label} contains a truncated ISO BMFF box`);
+    }
+    const size32 = view.getUint32(offset);
+    const type = isoBoxType(bytes, offset + 4);
+    if (!/^[\x20-\x7e]{4}$/u.test(type)) {
+      throw new Error(`${label} contains an invalid ISO BMFF box type`);
+    }
+    let headerBytes = 8;
+    let size = size32;
+    if (size32 === 1) {
+      if (end - offset < 16) {
+        throw new Error(`${label} contains a truncated extended-size ISO BMFF box`);
+      }
+      const extendedSize = view.getBigUint64(offset + 8);
+      if (extendedSize > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`${label} contains an oversized ISO BMFF box`);
+      }
+      size = Number(extendedSize);
+      headerBytes = 16;
+    } else if (size32 === 0) {
+      size = end - offset;
+    }
+    if (size < headerBytes || size > end - offset) {
+      throw new Error(`${label} contains an invalid ISO BMFF box size`);
+    }
+    boxes.push(Object.freeze({
+      end: offset + size,
+      payloadStart: offset + headerBytes,
+      type,
+    }));
+    offset += size;
+  }
+  if (offset !== end) throw new Error(`${label} contains trailing ISO BMFF bytes`);
+  return Object.freeze(boxes);
+}
+
+function oneIsoBox(
+  boxes: readonly IsoBox[],
+  type: string,
+  label: string,
+): IsoBox {
+  const matches = boxes.filter((box) => box.type === type);
+  if (matches.length !== 1) {
+    throw new Error(`${label} must contain exactly one ${type} box`);
+  }
+  return matches[0]!;
+}
+
+/**
+ * Validate one complete ISO BMFF file and return the dimensions from its one
+ * reviewed video track. This is deliberately a structural validator, not a
+ * codec or transcoder; the provider remains authoritative for media support.
+ */
+export function isoBmffVideoDimensions(
+  bytes: Uint8Array,
+  label: string,
+): Readonly<{ height: number; width: number }> {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const budget: IsoBoxBudget = { remaining: MAX_REVIEWED_ISO_BOXES };
+  const topLevel = isoBoxes(bytes, 0, bytes.byteLength, label, budget);
+  if (
+    topLevel[0]?.type !== "ftyp"
+    || topLevel[0].end - topLevel[0].payloadStart < 8
+  ) throw new Error(`${label} must begin with one bounded ISO BMFF file-type box`);
+  const moov = oneIsoBox(topLevel, "moov", label);
+  const movieBoxes = isoBoxes(
+    bytes,
+    moov.payloadStart,
+    moov.end,
+    `${label} movie box`,
+    budget,
+  );
+  const dimensions: { height: number; width: number }[] = [];
+  for (const track of movieBoxes.filter((box) => box.type === "trak")) {
+    const trackBoxes = isoBoxes(
+      bytes,
+      track.payloadStart,
+      track.end,
+      `${label} track`,
+      budget,
+    );
+    const media = oneIsoBox(trackBoxes, "mdia", `${label} track`);
+    const mediaBoxes = isoBoxes(
+      bytes,
+      media.payloadStart,
+      media.end,
+      `${label} media box`,
+      budget,
+    );
+    const handler = oneIsoBox(mediaBoxes, "hdlr", `${label} media box`);
+    if (handler.end - handler.payloadStart < 12) {
+      throw new Error(`${label} media handler is truncated`);
+    }
+    if (isoBoxType(bytes, handler.payloadStart + 8) !== "vide") continue;
+    const trackHeader = oneIsoBox(trackBoxes, "tkhd", `${label} track`);
+    const payloadBytes = trackHeader.end - trackHeader.payloadStart;
+    const version = bytes[trackHeader.payloadStart];
+    const dimensionOffset = version === 0 ? 76 : version === 1 ? 88 : -1;
+    const expectedPayloadBytes = version === 0 ? 84 : version === 1 ? 96 : -1;
+    if (dimensionOffset < 0 || payloadBytes !== expectedPayloadBytes) {
+      throw new Error(`${label} track header changed from the reviewed shape`);
+    }
+    const matrixOffset = trackHeader.payloadStart + dimensionOffset - 36;
+    for (const [index, expected] of IDENTITY_TRACK_MATRIX.entries()) {
+      if (view.getUint32(matrixOffset + index * 4) !== expected) {
+        throw new Error(`${label} track header has an unsupported transform matrix`);
+      }
+    }
+    const widthFixed = view.getUint32(trackHeader.payloadStart + dimensionOffset);
+    const heightFixed = view.getUint32(trackHeader.payloadStart + dimensionOffset + 4);
+    if ((widthFixed & 0xffff) !== 0 || (heightFixed & 0xffff) !== 0) {
+      throw new Error(`${label} dimensions must be whole pixels`);
+    }
+    const width = widthFixed >>> 16;
+    const height = heightFixed >>> 16;
+    if (width < 1 || height < 1 || width > 20_000 || height > 20_000) {
+      throw new Error(`${label} dimensions are outside the reviewed bound`);
+    }
+    dimensions.push({ height, width });
+  }
+  if (dimensions.length !== 1) {
+    throw new Error(`${label} must contain exactly one reviewed video track`);
+  }
+  return Object.freeze(dimensions[0]!);
+}
+
+export type IsoBmffMp4CompatibilityPolicy = Readonly<{
+  compatibleBrands: readonly string[];
+  rejectedMajorBrands: readonly string[];
+}>;
+
+function isoBmffBrandSet(
+  brands: readonly string[],
+  label: string,
+  allowEmpty: boolean,
+): ReadonlySet<string> {
+  if (
+    !Array.isArray(brands)
+    || (!allowEmpty && brands.length < 1)
+    || brands.some((brand) => (
+      typeof brand !== "string"
+      || !/^[\x20-\x7e]{4}$/u.test(brand)
+    ))
+    || new Set(brands).size !== brands.length
+  ) throw new Error(`${label} MP4 compatibility policy is invalid`);
+  return new Set(brands);
+}
+
+/**
+ * Validate the provider's explicit MP4 brand policy and project the duration
+ * and dimensions from one reviewed video track. This remains structural media
+ * validation: each provider owns the brands it is prepared to submit.
+ */
+export function isoBmffMp4VideoMetadata(
+  bytes: Uint8Array,
+  label: string,
+  policy: IsoBmffMp4CompatibilityPolicy,
+): Readonly<{
+  durationSeconds: number;
+  height: number;
+  width: number;
+}> {
+  if (
+    !(bytes instanceof Uint8Array)
+    || (
+      typeof SharedArrayBuffer !== "undefined"
+      && bytes.buffer instanceof SharedArrayBuffer
+    )
+    || bytes.byteLength < 24
+  ) throw new Error(`${label} must be one complete MP4 file`);
+  const compatibleBrands = isoBmffBrandSet(
+    policy.compatibleBrands,
+    label,
+    false,
+  );
+  const rejectedMajorBrands = isoBmffBrandSet(
+    policy.rejectedMajorBrands,
+    label,
+    true,
+  );
+  if ([...compatibleBrands].some((brand) => rejectedMajorBrands.has(brand))) {
+    throw new Error(`${label} MP4 compatibility policy is contradictory`);
+  }
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const fileTypeBytes = view.getUint32(0);
+  if (
+    fileTypeBytes < 16
+    || fileTypeBytes > bytes.byteLength
+    || isoBoxType(bytes, 4) !== "ftyp"
+    || (fileTypeBytes - 16) % 4 !== 0
+  ) throw new Error(`${label} must begin with one bounded MP4 file-type box`);
+  const budget: IsoBoxBudget = { remaining: MAX_REVIEWED_ISO_BOXES };
+  const topLevel = isoBoxes(bytes, 0, bytes.byteLength, label, budget);
+  const fileTypes = topLevel.filter((box) => box.type === "ftyp");
+  const fileType = fileTypes[0];
+  if (
+    topLevel[0] !== fileType
+    || fileTypes.length !== 1
+    || fileType === undefined
+    || fileType.end !== fileTypeBytes
+  ) throw new Error(`${label} must begin with one bounded MP4 file-type box`);
+  const majorBrand = isoBoxType(bytes, fileType.payloadStart);
+  const declaredBrands = [majorBrand];
+  for (
+    let offset = fileType.payloadStart + 8;
+    offset < fileType.end;
+    offset += 4
+  ) declaredBrands.push(isoBoxType(bytes, offset));
+  if (
+    rejectedMajorBrands.has(majorBrand)
+    || !declaredBrands.some((brand) => compatibleBrands.has(brand))
+  ) throw new Error(`${label} file-type box is not MP4-compatible`);
+
+  const dimensions = isoBmffVideoDimensions(bytes, label);
+  const movie = oneIsoBox(topLevel, "moov", label);
+  const movieBoxes = isoBoxes(
+    bytes,
+    movie.payloadStart,
+    movie.end,
+    `${label} movie box`,
+    budget,
+  );
+  const durations: number[] = [];
+  for (const track of movieBoxes.filter((box) => box.type === "trak")) {
+    const trackBoxes = isoBoxes(
+      bytes,
+      track.payloadStart,
+      track.end,
+      `${label} track`,
+      budget,
+    );
+    const media = oneIsoBox(trackBoxes, "mdia", `${label} track`);
+    const mediaBoxes = isoBoxes(
+      bytes,
+      media.payloadStart,
+      media.end,
+      `${label} media box`,
+      budget,
+    );
+    const handler = oneIsoBox(mediaBoxes, "hdlr", `${label} media box`);
+    if (handler.end - handler.payloadStart < 12) {
+      throw new Error(`${label} media handler is truncated`);
+    }
+    if (isoBoxType(bytes, handler.payloadStart + 8) !== "vide") continue;
+    const mediaHeader = oneIsoBox(mediaBoxes, "mdhd", `${label} media box`);
+    const payloadBytes = mediaHeader.end - mediaHeader.payloadStart;
+    const version = bytes[mediaHeader.payloadStart];
+    const timescaleOffset = version === 0 ? 12 : version === 1 ? 20 : -1;
+    const durationOffset = version === 0 ? 16 : version === 1 ? 24 : -1;
+    const expectedPayloadBytes = version === 0 ? 24 : version === 1 ? 36 : -1;
+    if (
+      timescaleOffset < 0
+      || durationOffset < 0
+      || payloadBytes !== expectedPayloadBytes
+    ) throw new Error(`${label} media header changed from the reviewed shape`);
+    const timescale = view.getUint32(mediaHeader.payloadStart + timescaleOffset);
+    if (timescale < 1) throw new Error(`${label} media timescale must be positive`);
+    const durationUnits = version === 0
+      ? BigInt(view.getUint32(mediaHeader.payloadStart + durationOffset))
+      : view.getBigUint64(mediaHeader.payloadStart + durationOffset);
+    const unknownDuration = version === 0
+      ? ISO_BMFF_UNKNOWN_DURATION_V0
+      : ISO_BMFF_UNKNOWN_DURATION_V1;
+    if (durationUnits === unknownDuration) {
+      throw new Error(`${label} media duration is the ISO BMFF unknown-duration sentinel`);
+    }
+    if (durationUnits < 1n || durationUnits > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error(`${label} media duration is outside the reviewed bound`);
+    }
+    const durationSeconds = Number(durationUnits) / timescale;
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+      throw new Error(`${label} media duration is invalid`);
+    }
+    durations.push(durationSeconds);
+  }
+  if (durations.length !== 1) {
+    throw new Error(`${label} must contain exactly one reviewed video duration`);
+  }
+  return Object.freeze({ durationSeconds: durations[0]!, ...dimensions });
+}

package/src/providers/linkedin-company-platform.ts

@@ -0,0 +1,42 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { readAttempt } from "../read-effect";
+import { readNative } from "../read-effect-platform";
+import type { WebSessionClient } from "../web-session-client";
+import type { LinkedInProfileBrowserTransport } from "./linkedin-web-profile-browser";
+
+export type LinkedInCompanyIdentity = {
+  readonly subject: string;
+};
+
+export type LinkedInCompanyNative = {
+  readonly openBrowser: () => Promise<LinkedInProfileBrowserTransport>;
+  readonly openDirect: () => Promise<WebSessionClient>;
+  readonly directIdentity: (client: WebSessionClient) => Promise<LinkedInCompanyIdentity>;
+  readonly decodeIdentity: (value: unknown) => LinkedInCompanyIdentity;
+  readonly bindIdentity: (identity: LinkedInCompanyIdentity) => string;
+  readonly readCompany: (client: WebSessionClient, url: string) => Promise<string>;
+  readonly observedAt: () => string;
+};
+
+function platform(ports: LinkedInCompanyNative) {
+  return {
+    openBrowser: readNative(ports.openBrowser),
+    closeBrowser: (browser: LinkedInProfileBrowserTransport) => readNative(() => browser.close()),
+    browserIdentity: (browser: LinkedInProfileBrowserTransport) => readNative(() => browser.currentIdentityResponse()).pipe(
+      Effect.flatMap(value => readAttempt(() => ports.decodeIdentity(value))),
+    ),
+    browserCompany: (browser: LinkedInProfileBrowserTransport, url: string) => readNative(() => browser.readOrganizationHtml(url)),
+    openDirect: readNative(ports.openDirect),
+    directIdentity: (client: WebSessionClient) => readNative(() => ports.directIdentity(client)),
+    bindIdentity: (identity: LinkedInCompanyIdentity) => readAttempt(() => ports.bindIdentity(identity)),
+    directCompany: (client: WebSessionClient, url: string) => readNative(() => ports.readCompany(client, url)),
+    observedAt: readAttempt(ports.observedAt),
+  };
+}
+
+export class LinkedInCompanyPlatform extends Context.Tag("wrench/LinkedInCompanyPlatform/v1")<LinkedInCompanyPlatform, ReturnType<typeof platform>>() { }
+
+export const LinkedInCompanyPlatformLive = (ports: LinkedInCompanyNative): Layer.Layer<LinkedInCompanyPlatform> =>
+  Layer.succeed(LinkedInCompanyPlatform, platform(ports));

package/src/providers/linkedin-company-program.ts

@@ -0,0 +1,88 @@
+import * as Effect from "effect/Effect";
+import * as Either from "effect/Either";
+import { PreservedBrowserArtifactsError } from "../browser";
+import { readAttempt, type ReadEffectFailure, withReadResource } from "../read-effect";
+import { readFailureProjection, type WebSessionExecution } from "../web-session-execution";
+import { LinkedInCompanyPlatform, type LinkedInCompanyIdentity } from "./linkedin-company-platform";
+import {
+  linkedInProfileIdentityAllowsBrowserFallback,
+  linkedInProfileReadFailure,
+} from "./linkedin-read-failure";
+import { projectLinkedInOrganizationStats, type LinkedInProfileTarget } from "./linkedin-web";
+
+/** The signed-in member authorizes the read; the company target is independently
+ * bound by the pure projection and need not match the member's personal slug. */
+export function linkedInCompanyReadProgram(
+  target: LinkedInProfileTarget,
+  preferBrowser: boolean,
+  diagnostic: (error: unknown, requestStage: string) => string,
+): Effect.Effect<WebSessionExecution, ReadEffectFailure, LinkedInCompanyPlatform> {
+  return Effect.gen(function*() {
+    const platform = yield* LinkedInCompanyPlatform;
+    let requestStage = preferBrowser
+      ? "contained-browser signed-in identity preflight"
+      : "signed-in identity preflight";
+    let identityMismatch = false;
+    const report = (error: ReadEffectFailure): Effect.Effect<WebSessionExecution, ReadEffectFailure> => {
+      if (error.cause instanceof PreservedBrowserArtifactsError) return Effect.fail(error);
+      return Effect.succeed({
+        status: "failed",
+        output: null,
+        finalUrl: target.url,
+        dispatchStarted: false,
+        dispatch: { planned: 0, started: 0, verified: 0 },
+        error: diagnostic(error.cause, requestStage),
+        readFailure: identityMismatch
+          ? readFailureProjection("account-mismatch")
+          : linkedInProfileReadFailure(error.cause),
+      });
+    };
+    const readBoundCompany = (
+      identity: LinkedInCompanyIdentity,
+      browser: boolean,
+      company: Effect.Effect<string, ReadEffectFailure>,
+    ): Effect.Effect<WebSessionExecution, ReadEffectFailure> => Effect.gen(function*() {
+      yield* platform.bindIdentity(identity).pipe(Effect.tapError(() => Effect.sync(() => { identityMismatch = true; })));
+      requestStage = browser ? "contained-browser public company page read" : "public company page read";
+      const html = yield* company;
+      requestStage = "exact company metric projection";
+      const observedAt = yield* platform.observedAt;
+      const output = yield* readAttempt(() => projectLinkedInOrganizationStats({
+        html,
+        organizationUrl: target.url,
+        observedAt,
+      }));
+      return {
+        status: "succeeded",
+        output,
+        finalUrl: target.url,
+        dispatchStarted: false,
+        dispatch: { planned: 0, started: 0, verified: 0 },
+      };
+    });
+    const browserRead = (): Effect.Effect<WebSessionExecution, ReadEffectFailure> => {
+      let closeFailed = false;
+      return withReadResource(
+        platform.openBrowser,
+        browser => platform.browserIdentity(browser).pipe(Effect.flatMap(identity => readBoundCompany(
+          identity, true, platform.browserCompany(browser, target.url),
+        ))),
+        browser => platform.closeBrowser(browser).pipe(Effect.tapError(() => Effect.sync(() => { closeFailed = true; }))),
+      ).pipe(Effect.catchTag("ReadEffectFailure", error => closeFailed ? Effect.fail(error) : report(error)));
+    };
+    if (preferBrowser) return yield* browserRead();
+    const direct = yield* Effect.either(platform.openDirect);
+    if (Either.isLeft(direct)) return yield* report(direct.left);
+    const identity = yield* Effect.either(platform.directIdentity(direct.right));
+    if (Either.isLeft(identity)) {
+      if (linkedInProfileIdentityAllowsBrowserFallback(identity.left.cause)) {
+        requestStage = "contained-browser signed-in identity preflight";
+        return yield* browserRead();
+      }
+      return yield* report(identity.left);
+    }
+    return yield* readBoundCompany(
+      identity.right, false, platform.directCompany(direct.right, target.url),
+    ).pipe(Effect.catchTag("ReadEffectFailure", report));
+  });
+}

package/src/providers/linkedin-contact-failure.ts

@@ -0,0 +1,84 @@
+import { OperationDeadlineError } from "../operation-deadline";
+import { readFailureProjection, type ReadFailureProjection } from "../web-session-execution";
+import {
+  LinkedInProfileBrowserFailure,
+  LinkedInProfileBrowserResponseRejectedError,
+} from "./linkedin-web-profile-browser";
+
+export type LinkedInContactStage = "identity" | "profile" | "contact" | "projection";
+
+/** Only the account-binding producer creates this category. Native wording is
+ * diagnostic data and cannot authorize account mismatch or auth repair. */
+export class LinkedInContactIdentityMismatch extends Error {
+  constructor(cause: unknown) {
+    super("LinkedIn current member no longer matches the bound auth subject", { cause });
+    this.name = "LinkedInContactIdentityMismatch";
+  }
+}
+
+export function linkedInContactReadFailure(
+  error: unknown,
+  stage: LinkedInContactStage,
+): ReadFailureProjection {
+  let deadlineCause: unknown = error;
+  for (let depth = 0; depth < 8 && deadlineCause !== undefined; depth += 1) {
+    if (deadlineCause instanceof OperationDeadlineError) {
+      return readFailureProjection(deadlineCause.failure === "timed-out" ? "operation-timeout" : "contract-drift");
+    }
+    deadlineCause = deadlineCause instanceof Error ? deadlineCause.cause : undefined;
+  }
+  let current: unknown = error;
+  for (let depth = 0; depth < 8 && current !== undefined; depth += 1) {
+    if (current instanceof LinkedInContactIdentityMismatch) return readFailureProjection("account-mismatch");
+    if (current instanceof LinkedInProfileBrowserResponseRejectedError) {
+      if (current.status === 401 || current.status === 403) return readFailureProjection("auth-repair-required");
+      if (current.status === 429) return readFailureProjection("provider-throttled");
+      if (current.status === 302 || current.status === 408 || current.status >= 500) {
+        return readFailureProjection("provider-temporary");
+      }
+      if (current.status === 404 && stage !== "identity") return readFailureProjection("target-unavailable");
+      return readFailureProjection("contract-drift");
+    }
+    if (current instanceof LinkedInProfileBrowserFailure) {
+      if (current.category === "authwall" || current.category === "session-cookie") {
+        return readFailureProjection("auth-repair-required");
+      }
+      if (
+        current.category === "startup"
+        || current.category === "execution-context"
+        || current.category === "provider-fetch"
+      ) {
+        return readFailureProjection("provider-temporary");
+      }
+      return readFailureProjection("contract-drift");
+    }
+    current = current instanceof Error ? current.cause : undefined;
+  }
+  return readFailureProjection("contract-drift");
+}
+
+const REQUEST_STAGE: Readonly<Record<LinkedInContactStage, string>> = {
+  identity: "contained-browser signed-in identity preflight",
+  profile: "contained-browser 1st-degree profile binding",
+  contact: "contained-browser Contact-info read",
+  projection: "exact Contact-info projection",
+};
+
+export function linkedInContactDiagnostic(error: unknown, stage: LinkedInContactStage): string {
+  let category = stage === "profile" ? "1st-degree relationship binding"
+    : stage === "projection" ? "exact Contact-info projection" : "reviewed response projection";
+  let current: unknown = error;
+  for (let depth = 0; depth < 8 && current !== undefined; depth += 1) {
+    if (current instanceof LinkedInContactIdentityMismatch) {
+      category = "signed-in account binding";
+      break;
+    }
+    if (current instanceof LinkedInProfileBrowserFailure) {
+      if (current.category === "authwall") category = "signed-out authwall";
+      if (current.category === "session-cookie") category = "signed-in session cookie";
+      break;
+    }
+    current = current instanceof Error ? current.cause : undefined;
+  }
+  return `LinkedIn contacts.read failed during ${REQUEST_STAGE[stage]} at ${category}; no remote write occurred`;
+}

package/src/providers/linkedin-contact-platform.ts

@@ -0,0 +1,45 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ReadEffectFailure, readAttempt } from "../read-effect";
+import { readNative } from "../read-effect-platform";
+import { LinkedInContactIdentityMismatch } from "./linkedin-contact-failure";
+import type { LinkedInContactInfoJsonInput } from "./linkedin-web-contact";
+import type { LinkedInProfileBrowserTransport } from "./linkedin-web-profile-browser";
+
+export type LinkedInContactIdentity = { readonly subject: string };
+
+export type LinkedInContactNative = {
+  readonly openBrowser: () => Promise<LinkedInProfileBrowserTransport>;
+  readonly decodeIdentity: (value: unknown) => LinkedInContactIdentity;
+  readonly bindIdentity: (identity: LinkedInContactIdentity) => string;
+  readonly observedAt: () => string;
+};
+
+function platform(ports: LinkedInContactNative) {
+  return {
+    openBrowser: readNative(ports.openBrowser).pipe(Effect.uninterruptible),
+    identity: (browser: LinkedInProfileBrowserTransport) => readNative(() => browser.currentIdentityResponse()).pipe(
+      Effect.uninterruptible,
+      Effect.flatMap(value => readAttempt(() => ports.decodeIdentity(value))),
+    ),
+    bindIdentity: (identity: LinkedInContactIdentity) => readAttempt(() => ports.bindIdentity(identity)).pipe(
+      Effect.mapError(error => new ReadEffectFailure({ cause: new LinkedInContactIdentityMismatch(error.cause) })),
+    ),
+    profileHtml: (browser: LinkedInProfileBrowserTransport, profileUrl: string) =>
+      readNative(() => browser.readProfileHtml(profileUrl)).pipe(Effect.uninterruptible),
+    contactPayload: (browser: LinkedInProfileBrowserTransport, input: LinkedInContactInfoJsonInput) =>
+      readNative(() => browser.readContactInfoJson(input)).pipe(Effect.uninterruptible),
+    observedAt: readAttempt(ports.observedAt),
+    closeBrowser: (browser: LinkedInProfileBrowserTransport) =>
+      readNative(() => browser.close()).pipe(Effect.uninterruptible),
+  };
+}
+
+export class LinkedInContactPlatform extends Context.Tag("wrench/LinkedInContactPlatform/v1")<
+  LinkedInContactPlatform,
+  ReturnType<typeof platform>
+>() { }
+
+export const LinkedInContactPlatformLive = (ports: LinkedInContactNative): Layer.Layer<LinkedInContactPlatform> =>
+  Layer.succeed(LinkedInContactPlatform, platform(ports));

package/src/providers/linkedin-contact-program.ts

@@ -0,0 +1,91 @@
+import * as Effect from "effect/Effect";
+import { PreservedBrowserArtifactsError } from "../browser";
+import { readAttempt, type ReadEffectFailure, withReadResource } from "../read-effect";
+import type { WebSessionExecution } from "../web-session-execution";
+import { LinkedInContactPlatform } from "./linkedin-contact-platform";
+import {
+  linkedInContactDiagnostic,
+  linkedInContactReadFailure,
+  type LinkedInContactStage,
+} from "./linkedin-contact-failure";
+import {
+  projectLinkedInContactInfo,
+  projectLinkedInEmbeddedContactFields,
+  projectLinkedInProfileContactBinding,
+  resolveLinkedInProfileContactInfoQueryId,
+  type LinkedInContactInfoTarget,
+} from "./linkedin-web-contact";
+
+export function linkedInContactReadProgram(
+  target: LinkedInContactInfoTarget,
+): Effect.Effect<WebSessionExecution, ReadEffectFailure, LinkedInContactPlatform> {
+  return Effect.gen(function*() {
+    const platform = yield* LinkedInContactPlatform;
+    let stage: LinkedInContactStage = "identity";
+    let closeFailed = false;
+    return yield* withReadResource(
+      platform.openBrowser,
+      browser => Effect.gen(function*() {
+        const identity = yield* platform.identity(browser);
+        yield* platform.bindIdentity(identity);
+        stage = "profile";
+        const profileHtml = yield* platform.profileHtml(browser, target.url);
+        const binding = yield* readAttempt(() => projectLinkedInProfileContactBinding({
+          profileHtml,
+          profileUrl: target.url,
+          expectedViewerSubject: identity.subject,
+        }));
+        const embedded = yield* readAttempt(() =>
+          projectLinkedInEmbeddedContactFields(profileHtml, binding.vanity)
+        );
+        let contactPayload: unknown;
+        if (embedded !== undefined && embedded.email !== null) {
+          contactPayload = Object.freeze({
+            emailAddress: embedded.email,
+            connectedAt: embedded.connectedSince,
+            phoneNumbers: embedded.phones,
+            websites: embedded.websites,
+            birthDateOn: embedded.birthday,
+            profileUrl: embedded.profileUrl,
+          });
+        } else {
+          stage = "contact";
+          const queryId = resolveLinkedInProfileContactInfoQueryId(profileHtml);
+          contactPayload = yield* platform.contactPayload(browser, {
+            profileUrl: target.url,
+            profileUrn: binding.profileUrn,
+            ...(queryId === undefined ? {} : { queryId }),
+          });
+        }
+        stage = "projection";
+        const observedAt = yield* platform.observedAt;
+        const output = yield* readAttempt(() => projectLinkedInContactInfo({
+          profileHtml,
+          contactPayload,
+          profileUrl: target.url,
+          expectedViewerSubject: identity.subject,
+          observedAt,
+        }));
+        return {
+          status: "succeeded" as const,
+          output,
+          finalUrl: target.url,
+          dispatchStarted: false,
+          dispatch: { planned: 0, started: 0, verified: 0 },
+        };
+      }),
+      browser => platform.closeBrowser(browser).pipe(Effect.tapError(() => Effect.sync(() => { closeFailed = true; }))),
+    ).pipe(Effect.catchTag("ReadEffectFailure", error => {
+      if (closeFailed || error.cause instanceof PreservedBrowserArtifactsError) return Effect.fail(error);
+      return Effect.succeed({
+        status: "failed" as const,
+        output: null,
+        finalUrl: target.url,
+        dispatchStarted: false,
+        dispatch: { planned: 0, started: 0, verified: 0 },
+        error: linkedInContactDiagnostic(error.cause, stage),
+        readFailure: linkedInContactReadFailure(error.cause, stage),
+      });
+    }));
+  });
+}