@volter/twin-linkedin 0.1.0

package/dist/src/linkedin-mirror-ui.js

@@ -0,0 +1,174 @@
+// LINKEDIN MIRROR UI — linkedin.com's own view of the twin's state: an organization's company page
+// (its header with logo, name and follower line, and its Posts feed), a post card with commentary
+// and an inline video player or image or article card, and a single post's page. A React/TSX app
+// bundled by Bun that renders by consuming the twin's OWN LinkedIn API on the same origin
+// (GET /v2/userinfo, /rest/organizationAcls, /rest/organizations, /rest/networkSizes,
+// /rest/posts?q=author, /rest/posts/{urn}, /rest/images/{urn}, /rest/videos/{urn}) — the same routes
+// any LinkedIn client uses — so every screen is data-coupled to real twin state. Archetype A
+// (passthrough), transcribed from the X mirror: one serving code path, so API↔UI parity cannot drift.
+//
+// SIGN-IN. linkedin.com's own two-step sign-in (email, then password) with the password leg replaced
+// by the access token the twin issued through /_twin/tokens: the mirror is a client like any other
+// and presents a registered token rather than bypassing the auth gate. The email is checked against
+// the token's own member (`/v2/userinfo`), and the page it opens is the organization that member
+// administers (`organizationAcls?q=roleAssignee`). Both are kept in the TAB'S sessionStorage.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's own
+// fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse, serveHttp } from '@volter/world-core';
+import { createLinkedinTwinFetch } from "./linkedin-server.js";
+const CLIENT_ENTRY = () => new URL('../client/linkedin-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/linkedin-mirror.css', import.meta.url).pathname;
+/** The version the mirror's reads pin — the twin's newest. */
+export const MIRROR_VERSION = '202609';
+/** linkedin.com's feed timestamp: "now", "5m", "3h", "2d", "1w", "3mo", "1yr". `nowMs` is passed in. */
+export function relativeTime(ms, nowMs) {
+    if (typeof ms !== 'number' || !Number.isFinite(ms))
+        return '';
+    const s = Math.max(0, Math.floor((nowMs - ms) / 1000));
+    if (s < 60)
+        return 'now';
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    if (s < 86_400)
+        return `${Math.floor(s / 3600)}h`;
+    if (s < 7 * 86_400)
+        return `${Math.floor(s / 86_400)}d`;
+    if (s < 30 * 86_400)
+        return `${Math.floor(s / (7 * 86_400))}w`;
+    if (s < 365 * 86_400)
+        return `${Math.floor(s / (30 * 86_400))}mo`;
+    return `${Math.floor(s / (365 * 86_400))}yr`;
+}
+/** "12,480 followers" — the follower line under a page's name and a post's author. */
+export function followerLine(count) {
+    const n = typeof count === 'number' && Number.isFinite(count) ? count : 0;
+    return `${n.toLocaleString('en-US')} ${n === 1 ? 'follower' : 'followers'}`;
+}
+/**
+ * A post's commentary as linkedin.com draws it, from the little text format LinkedIn stores:
+ * `{hashtag|\#|coding}` is the hashtag `#coding`, `@[Devtestco](urn:li:organization:2414183)` the
+ * mention `Devtestco`, a URL a link; everything else plain text (backslash escapes undone).
+ */
+export function commentarySegments(commentary) {
+    const source = typeof commentary === 'string' ? commentary : '';
+    const out = [];
+    const re = /\{hashtag\|\\?#\|([^}]+)\}|@\[([^\]]+)\]\((urn:li:[A-Za-z]+:[A-Za-z0-9_-]+)\)|(https?:\/\/[^\s]+)/g;
+    let last = 0;
+    const text = (s) => { if (s !== '')
+        out.push({ kind: 'text', value: s.replace(/\\([()[\]{}<>@|~_*#\\])/g, '$1') }); };
+    for (const m of source.matchAll(re)) {
+        const at = m.index ?? 0;
+        text(source.slice(last, at));
+        if (m[1] !== undefined)
+            out.push({ kind: 'hashtag', value: `#${m[1]}` });
+        else if (m[2] !== undefined)
+            out.push({ kind: 'mention', value: m[2], urn: m[3] });
+        else {
+            const value = m[4].replace(/[.,;:!?)\]'"]+$/, '');
+            out.push({ kind: 'url', value });
+            last = at + value.length;
+            continue;
+        }
+        last = at + m[0].length;
+    }
+    text(source.slice(last));
+    return out;
+}
+/** Whether a commentary needs linkedin.com's "…more" fold: over three lines or ~210 characters. */
+export function needsFold(commentary) {
+    const s = typeof commentary === 'string' ? commentary : '';
+    return s.split('\n').length > 3 || s.length > 210;
+}
+/** The kind of asset a post's content names, from its URN. */
+export function mediaKind(post) {
+    const content = post.content;
+    if (content?.article)
+        return 'article';
+    const id = content?.media?.id;
+    if (typeof id !== 'string')
+        return undefined;
+    if (id.startsWith('urn:li:video:'))
+        return 'video';
+    if (id.startsWith('urn:li:image:'))
+        return 'image';
+    return undefined;
+}
+/** A URL's host, as an article card prints its source ("github.com"). */
+export function sourceHost(url) {
+    try {
+        return new URL(String(url)).host.replace(/^www\./, '');
+    }
+    catch {
+        return '';
+    }
+}
+export function orgFromReads(pub, admin, size, logo) {
+    return {
+        id: Number(pub.id), urn: `urn:li:organization:${pub.id}`, name: String(pub.localizedName), vanity: String(pub.vanityName),
+        ...(logo && typeof logo.downloadUrl === 'string' ? { logoUrl: logo.downloadUrl } : {}),
+        ...(size && typeof size.firstDegreeSize === 'number' ? { followers: size.firstDegreeSize } : {}),
+        ...(admin && typeof admin.localizedDescription === 'string' ? { description: admin.localizedDescription } : {}),
+        ...(typeof pub.localizedWebsite === 'string' ? { website: pub.localizedWebsite } : {}),
+    };
+}
+/** The mirror's own route for a post: linkedin.com's `/feed/update/<urn>`. */
+export function postRoute(urn) {
+    return `#/feed/update/${encodeURIComponent(urn)}`;
+}
+/** The finder read a company page's feed draws. */
+export function postsQuery(orgUrn, start = 0) {
+    return `/rest/posts?q=author&author=${encodeURIComponent(orgUrn)}&count=10&start=${start}&sortBy=CREATED`;
+}
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>LinkedIn</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+/** Build the React/TSX mirror client to browser JS; memoized at module scope, so a pack on its own
+ *  does exactly one `Bun.build`. */
+export function buildLinkedinMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY()).catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/** Serve the LinkedIn mirror UI (React app) + its backing LinkedIn API on one origin. */
+export async function createLinkedinMirrorServer(options) {
+    const twin = createLinkedinTwinFetch(options);
+    const server = await serveHttp({
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildLinkedinMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // Everything else -> the twin's OWN FETCH ADAPTER, the same closure createLinkedinTwinServer serves.
+            return twin(request);
+        },
+    });
+    const port = server.port ?? options.port ?? 0;
+    return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}
+/** The app-shell HTML (pure). */
+export function linkedinMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function linkedinMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/linkedin-server.d.ts

@@ -0,0 +1,10 @@
+export interface LinkedinTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createLinkedinTwinFetch(options?: LinkedinTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createLinkedinTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<import("@volter/world-core").HttpServer>;

package/dist/src/linkedin-server.js

@@ -0,0 +1,154 @@
+// LinkedIn twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler` — manifest door, body read, header map,
+// worldNow() stamp, JSON reply); this file contributes only VALUES — plus the two places LinkedIn's
+// wire exceeds that adapter's text-in/JSON-out shape, both about media BYTES:
+//
+//   - the upload PUTs to the signed `/dms-uploads/…` URLs carry raw bytes, which the adapter's
+//     `request.text()` would corrupt, so they are read here and handed to the same handler as `bytes`;
+//   - the asset bytes themselves, read from the blob seam by digest at LinkedIn's own path shapes —
+//     media.licdn.com's `/dms/image/<asset>/<rendition>/0/<digest>` for an image or a video's
+//     thumbnail, dms.licdn.com's `/playlist/<asset>/<rendition>/0/<digest>` for a video file — with
+//     HTTP Range (206), so a <video> can seek, through the kernel's ranged reads. Those URLs are public at LinkedIn (a feed's <img> and
+//     <video> carry no bearer), so these routes are too.
+import { handleLinkedinTwinRequest } from "./linkedin-twin.js";
+import { assetAsOf, blobKey, readAsset as readStoredAsset, videoPosterSvg } from "./linkedin-media.js";
+import { createTwinFetchFromHandler, readResourceBlobRange, resourceBlobSize, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+const SERVICE = 'linkedin';
+const UPLOAD_PATH = /^\/dms-uploads\//;
+const IMAGE_BYTES = /^\/dms\/image\/([A-Za-z0-9_-]{8,40})\/(image-shrink_1280|ads-video-thumbnail_720_1280)\/0\/([0-9a-f]{64}|system)$/;
+const VIDEO_BYTES = /^\/playlist\/([A-Za-z0-9_-]{8,40})\/mp4-\d+p-30fp-crf28\/0\/([0-9a-f]{64})$/;
+/** The most one read of the blob seam returns: an open-ended `bytes=N-` is answered with at most
+ *  this much (a player asks again from where it stands), and any longer answer — a whole file, a long
+ *  closed or suffix range — is streamed in reads of this size, so no request holds a large file. */
+const RANGE_CAP = 8 * 1024 * 1024;
+/** [start, end] of a stored digest as a body: one read when it fits the cap, else a stream of capped reads. */
+async function rangeBody(key, start, end, root) {
+    if (end - start + 1 <= RANGE_CAP) {
+        const bytes = await readResourceBlobRange(SERVICE, key, start, end, root);
+        return bytes === null ? null : new Blob([new Uint8Array(bytes)]);
+    }
+    let at = start;
+    return new ReadableStream({
+        async pull(controller) {
+            if (at > end) {
+                controller.close();
+                return;
+            }
+            const chunk = await readResourceBlobRange(SERVICE, key, at, Math.min(end, at + RANGE_CAP - 1), root);
+            if (chunk === null || chunk.length === 0) {
+                controller.error(new Error('the stored bytes went away mid-read'));
+                return;
+            }
+            at += chunk.length;
+            controller.enqueue(new Uint8Array(chunk));
+        },
+    });
+}
+/**
+ * A stored digest as a response, read through the kernel's ranged reads (which walk the branch's
+ * ancestors), honouring a single `Range: bytes=` (206 / 416) as a CDN does.
+ */
+async function bytesResponse(request, sha256, contentType, root) {
+    const key = blobKey(sha256);
+    const total = await resourceBlobSize(SERVICE, key, root);
+    if (total === null)
+        return notFound();
+    const base = { 'content-type': contentType, 'accept-ranges': 'bytes', 'cache-control': 'public, max-age=604800, immutable' };
+    let start = 0;
+    let end = total - 1;
+    const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
+    if (range && (range[1] !== '' || range[2] !== '')) {
+        if (range[1] === '') {
+            start = Math.max(0, total - Number(range[2]));
+        }
+        else {
+            start = Number(range[1]);
+            end = range[2] === '' ? Math.min(total - 1, start + RANGE_CAP - 1) : Math.min(Number(range[2]), total - 1);
+        }
+        if (start >= total || start > end)
+            return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
+    }
+    const partial = start !== 0 || end !== total - 1;
+    const headers = { ...base, 'content-length': String(end - start + 1), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) };
+    if (request.method === 'HEAD')
+        return new Response(null, { status: partial ? 206 : 200, headers });
+    const body = await rangeBody(key, start, end, root);
+    if (body === null)
+        return notFound();
+    return new Response(body, { status: partial ? 206 : 200, headers });
+}
+/** An asset as it stands at the world's instant (a finalized video becomes AVAILABLE with time). */
+async function readAsset(id, root) {
+    const stored = await readStoredAsset(id, root);
+    return stored ? assetAsOf(stored, Date.parse(worldNow())) : undefined;
+}
+const notFound = () => Response.json({ status: 404, code: 'NOT_FOUND', message: 'Not Found' }, { status: 404 });
+export function createLinkedinTwinFetch(options = {}) {
+    const adapted = createTwinFetchFromHandler(handleLinkedinTwinRequest, {
+        ...options,
+        extras: (request) => ({ publicBase: twinPublicBase(request) }),
+        manifest: statefulTwinManifest({ vendor: 'linkedin', twinOf: 'the LinkedIn Community Management API (organization posts, images, videos)', stores: 'organizations, admin roles, posts, and uploaded images and videos' }),
+    });
+    const serve = async (request) => {
+        const url = new URL(request.url);
+        const reading = request.method === 'GET' || request.method === 'HEAD';
+        const image = reading ? IMAGE_BYTES.exec(url.pathname) : null;
+        if (image) {
+            const asset = await readAsset(image[1], options.root);
+            if (!asset || asset.status !== 'AVAILABLE')
+                return notFound();
+            const thumbnail = image[2] === 'ads-video-thumbnail_720_1280';
+            if (thumbnail && asset.kind !== 'video')
+                return notFound();
+            if (thumbnail && image[3] === 'system') {
+                if (asset.thumbnail_sha256)
+                    return notFound();
+                return new Response(request.method === 'HEAD' ? null : videoPosterSvg(asset.width ?? 0, asset.height ?? 0), { headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=604800' } });
+            }
+            const sha = thumbnail ? asset.thumbnail_sha256 : asset.kind === 'image' ? asset.sha256 : undefined;
+            if (!sha || sha !== image[3])
+                return notFound();
+            return bytesResponse(request, sha, (thumbnail ? asset.thumbnail_media_type : asset.media_type) ?? 'application/octet-stream', options.root);
+        }
+        const video = reading ? VIDEO_BYTES.exec(url.pathname) : null;
+        if (video) {
+            const asset = await readAsset(video[1], options.root);
+            if (!asset || asset.kind !== 'video' || asset.status !== 'AVAILABLE' || asset.sha256 !== video[2])
+                return notFound();
+            return bytesResponse(request, asset.sha256, 'video/mp4', options.root);
+        }
+        if (request.method === 'PUT' && UPLOAD_PATH.test(url.pathname)) {
+            const bytes = new Uint8Array(await request.arrayBuffer());
+            const headers = {};
+            request.headers.forEach((value, key) => { headers[key] = value; });
+            const invoke = () => handleLinkedinTwinRequest({
+                method: request.method,
+                path: url.pathname + (url.search || ''),
+                headers,
+                bytes,
+                readOnly: options.readOnly ?? false,
+                occurredAt: worldNow(),
+                publicBase: twinPublicBase(request),
+                ...(options.root !== undefined ? { root: options.root } : {}),
+            });
+            const requestId = request.headers.get('x-twins-request-id') ?? undefined;
+            const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+            const empty = result.body === null || result.body === undefined || result.body === '';
+            return new Response(empty ? null : JSON.stringify(result.body), { status: result.status, headers: { ...(empty ? {} : { 'content-type': 'application/json' }), ...result.headers } });
+        }
+        return adapted(request);
+    };
+    // every answer carries the World's instant as its HTTP Date (an HTTP server's own header), so a
+    // client — the mirror's relative times — reads the World's now rather than its own clock
+    return async (request) => {
+        const res = await serve(request);
+        const headers = new Headers(res.headers);
+        headers.set('date', new Date(worldNow()).toUTCString());
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    };
+}
+export async function createLinkedinTwinServer(options = {}) {
+    return serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createLinkedinTwinFetch(options) });
+}

package/dist/src/linkedin-twin.d.ts

@@ -0,0 +1,23 @@
+import { type LinkedinResponse } from './linkedin-errors.js';
+export type LinkedinRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    readOnly?: boolean;
+    occurredAt?: string;
+    root?: string;
+    /** The raw bytes of an upload PUT (linkedin-server.ts reads them; the JSON adapter would corrupt binary). */
+    bytes?: Uint8Array;
+    /** Where this twin is reached (`twinPublicBase`). Upload and download URLs are minted from it; a
+     *  direct handler call with none mints LinkedIn's own hosts. */
+    publicBase?: string;
+};
+type Resource = Record<string, any>;
+/** The API versions LinkedIn serves on 2026-09-26 (the versioned docs' moniker list). */
+export declare const ACTIVE_VERSIONS: readonly ["202510", "202511", "202601", "202602", "202603", "202604", "202605", "202606", "202607", "202608", "202609"];
+export declare function templateHashtags(commentary: string): string;
+/** A stored post as LinkedIn answers it: its vendor fields, no `_` bookkeeping. */
+export declare function projectPost(post: Resource): Record<string, unknown>;
+export declare function handleLinkedinTwinRequest(req: LinkedinRequest): Promise<LinkedinResponse>;
+export {};