@volter/twin-instagram 0.1.0

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

@@ -0,0 +1,158 @@
+// INSTAGRAM MIRROR UI — instagram.com's own view of the twin's state: a professional account's
+// profile (its avatar, username, name, bio, and the posts / followers / following counts it holds),
+// its Reels grid (9:16 tiles with a play glyph), and a Reel viewer (a full-height vertical player with
+// the caption and username over it). A React/TSX app bundled by Bun that renders by consuming the
+// twin's OWN Graph API on the same origin (GET /v26.0/me and GET /v26.0/{ig-user-id}/media) — the same
+// routes any Instagram Platform client uses — so every screen is data-coupled to real twin state.
+// Archetype A (passthrough), transcribed from the X and LinkedIn mirrors: one serving code path, so
+// API↔UI parity cannot drift.
+//
+// SIGN-IN. instagram.com's login (username, then password) with the password 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 username is checked against the token's
+// own account (`/me?fields=username`). Both are kept in the TAB'S sessionStorage.
+//
+// ROUTES are `#/…` hash routes, reached by LINKS (`<a href="#/…">`) — never by assigning location — so
+// under a World's <base> the served shell's own link handler keeps them on the shell
+// (world-core's mirror-shell.ts).
+//
+// 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 { createInstagramTwinFetch } from "./instagram-server.js";
+const CLIENT_ENTRY = () => new URL('../client/instagram-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/instagram-mirror.css', import.meta.url).pathname;
+/** The version the mirror's reads pin — the twin's newest. */
+export const MIRROR_VERSION = 'v26.0';
+/** The account fields the profile header reads. */
+export const PROFILE_FIELDS = 'id,username,name,biography,website,followers_count,follows_count,media_count,profile_picture_url';
+/** The media fields the grid and the viewer read. */
+export const REEL_FIELDS = 'id,media_type,media_product_type,media_url,thumbnail_url,permalink,caption,timestamp,shortcode,username,like_count,comments_count,is_shared_to_feed';
+/** instagram.com's count: "1,234" below ten thousand, then "12.5K", "1.2M" (one decimal, trailing .0 dropped). */
+export function compactCount(n) {
+    const v = typeof n === 'number' && Number.isFinite(n) ? n : 0;
+    const one = (x, unit) => `${(Math.floor(x * 10) / 10).toFixed(1).replace(/\.0$/, '')}${unit}`;
+    if (v >= 1_000_000)
+        return one(v / 1_000_000, 'M');
+    if (v >= 10_000)
+        return one(v / 1_000, 'K');
+    return v.toLocaleString('en-US');
+}
+/** instagram.com's age of a post: "now", "5m", "3h", "2d", "3w", then the date ("March 4" / "March 4, 2025"). */
+export function timeAgo(timestamp, nowMs) {
+    const ms = Date.parse(String(timestamp ?? '').replace(/([+-]\d\d)(\d\d)$/, '$1:$2'));
+    if (!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`;
+    const d = new Date(ms);
+    const month = d.toLocaleString('en-US', { month: 'long', timeZone: 'UTC' });
+    return d.getUTCFullYear() === new Date(nowMs).getUTCFullYear() ? `${month} ${d.getUTCDate()}` : `${month} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}
+/** A caption as instagram.com draws it: `#tag` and `@user` as links, everything else text. */
+export function captionSegments(caption) {
+    const source = typeof caption === 'string' ? caption : '';
+    const out = [];
+    let last = 0;
+    for (const m of source.matchAll(/(^|[^\w&])([#@])([\p{L}\p{N}_.]*[\p{L}\p{N}_])/gu)) {
+        const at = (m.index ?? 0) + m[1].length;
+        if (at > last)
+            out.push({ kind: 'text', value: source.slice(last, at) });
+        out.push({ kind: m[2] === '#' ? 'hashtag' : 'mention', value: `${m[2]}${m[3]}` });
+        last = at + 1 + m[3].length;
+    }
+    if (last < source.length)
+        out.push({ kind: 'text', value: source.slice(last) });
+    return out;
+}
+export function profileFromRead(me) {
+    return {
+        id: String(me.id), username: String(me.username),
+        ...(typeof me.name === 'string' && me.name !== '' ? { name: me.name } : {}),
+        ...(typeof me.biography === 'string' && me.biography !== '' ? { biography: me.biography } : {}),
+        ...(typeof me.website === 'string' && me.website !== '' ? { website: me.website } : {}),
+        ...(typeof me.profile_picture_url === 'string' ? { avatarUrl: me.profile_picture_url } : {}),
+        ...(typeof me.media_count === 'number' ? { posts: me.media_count } : {}),
+        ...(typeof me.followers_count === 'number' ? { followers: me.followers_count } : {}),
+        ...(typeof me.follows_count === 'number' ? { following: me.follows_count } : {}),
+    };
+}
+/** Whether a media is a Reel (the Content Publishing guide: request media_product_type, since a
+ *  published Reel's media_type reads VIDEO). */
+export function isReel(m) {
+    return m.media_product_type === 'REELS';
+}
+/** What a profile's tab shows: the Reels tab every Reel; the Posts tab only those shared to the feed
+ *  (IG Media: `is_shared_to_feed` false "indicates the reel can only appear in the Reels tab"). */
+export function tabReels(reels, tab) {
+    return tab === 'reels' ? reels : reels.filter((r) => r.is_shared_to_feed !== false);
+}
+/** The mirror's own route for a Reel: instagram.com's `/reel/<shortcode>/`. */
+export function reelRoute(shortcode) {
+    return `#/reel/${encodeURIComponent(shortcode)}/`;
+}
+/** The read the grid and the viewer draw: the account's media, newest first. */
+export function mediaQuery(userId, after) {
+    return `/${MIRROR_VERSION}/${userId}/media?fields=${REEL_FIELDS}&limit=24${after ? `&after=${encodeURIComponent(after)}` : ''}`;
+}
+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>Instagram</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 buildInstagramMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY()).catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/** Serve the Instagram mirror UI (React app) + its backing Graph API on one origin. */
+export async function createInstagramMirrorServer(options) {
+    const twin = createInstagramTwinFetch(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 buildInstagramMirrorClient(), { 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 createInstagramTwinServer 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 instagramMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function instagramMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

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

@@ -0,0 +1,14 @@
+export interface InstagramTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+/** 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. */
+export declare const RANGE_CAP: number;
+export declare function createInstagramTwinFetch(options?: InstagramTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createInstagramTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<import("@volter/world-core").HttpServer>;

package/dist/src/instagram-server.js

@@ -0,0 +1,146 @@
+// Instagram 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 Instagram's
+// wire exceeds that adapter's text-in/JSON-out shape, both about media BYTES:
+//
+//   - the rupload POSTs (rupload.facebook.com/ig-api-upload/…) carry raw video bytes, which the
+//     adapter's `request.text()` would corrupt, so they are read here and handed to the same handler
+//     as `bytes`;
+//   - the bytes themselves, read from the blob seam by digest at the CDN's path shapes — a Reel's
+//     `media_url` (`/o1/v/t16/f2/m86/<digest>.mp4`), its stand-in thumbnail
+//     (`/v/t51.71878-15/<digest>_poster.svg`) and a profile picture (`/v/t51.2885-19/<digest>.jpg|png`)
+//     — with HTTP Range (206/416), so a <video> can seek, through the kernel's ranged reads. Those URLs
+//     are public at Instagram's CDN (a page's <video> carries no token), so these routes are too, and
+//     they serve only a digest a held media or profile names.
+import { handleInstagramTwinRequest } from "./instagram-twin.js";
+import { blobKey, reelPosterSvg } from "./instagram-media.js";
+import { createTwinFetchFromHandler, ownFields, projectResources, readResourceBlobRange, resourceBlobSize, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+const SERVICE = 'instagram';
+const RUPLOAD_PATH = /^\/ig-api-upload\//;
+const REEL_BYTES = /^\/o1\/v\/t16\/f2\/m86\/([0-9a-f]{64})\.mp4$/;
+const REEL_POSTER = /^\/v\/t51\.71878-15\/([0-9a-f]{64})_poster\.svg$/;
+const PROFILE_PICTURE = /^\/v\/t51\.2885-19\/([0-9a-f]{64})\.(jpg|png)$/;
+/** 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. */
+export const RANGE_CAP = 8 * 1024 * 1024;
+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, 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 });
+}
+const notFound = () => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+/** The live media whose Reel is this digest, if any. */
+function mediaWithVideo(sha256, root) {
+    return projectResources(SERVICE, root).map((r) => ({ r, f: ownFields(r) }))
+        .find(({ r, f }) => r.type === 'media' && f._deleted !== true && f.deleted !== true && f._video?.sha256 === sha256)?.f;
+}
+function userWithPicture(sha256, root) {
+    return projectResources(SERVICE, root).map((r) => ({ r, f: ownFields(r) }))
+        .find(({ r, f }) => r.type === 'ig_user' && f._profile_picture?.sha256 === sha256)?.f;
+}
+export function createInstagramTwinFetch(options = {}) {
+    const adapted = createTwinFetchFromHandler(handleInstagramTwinRequest, {
+        ...options,
+        extras: (request) => ({ publicBase: twinPublicBase(request) }),
+        manifest: statefulTwinManifest({ vendor: 'instagram', twinOf: 'the Instagram Platform content publishing API (Reels, resumable upload)', stores: 'professional accounts, published Reels, and staged media containers' }),
+    });
+    const serve = async (request) => {
+        const url = new URL(request.url);
+        const reading = request.method === 'GET' || request.method === 'HEAD';
+        const reel = reading ? REEL_BYTES.exec(url.pathname) : null;
+        if (reel)
+            return mediaWithVideo(reel[1], options.root) ? bytesResponse(request, reel[1], 'video/mp4', options.root) : notFound();
+        const poster = reading ? REEL_POSTER.exec(url.pathname) : null;
+        if (poster) {
+            const media = mediaWithVideo(poster[1], options.root);
+            if (!media)
+                return notFound();
+            return new Response(request.method === 'HEAD' ? null : reelPosterSvg(Number(media._video.width ?? 0), Number(media._video.height ?? 0)), { headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=604800' } });
+        }
+        const picture = reading ? PROFILE_PICTURE.exec(url.pathname) : null;
+        if (picture) {
+            const user = userWithPicture(picture[1], options.root);
+            return user ? bytesResponse(request, picture[1], String(user._profile_picture.media_type), options.root) : notFound();
+        }
+        if ((request.method === 'POST' || request.method === 'GET') && RUPLOAD_PATH.test(url.pathname)) {
+            const bytes = request.method === 'POST' ? new Uint8Array(await request.arrayBuffer()) : undefined;
+            const headers = {};
+            request.headers.forEach((value, key) => { headers[key] = value; });
+            const invoke = () => handleInstagramTwinRequest({
+                method: request.method,
+                path: url.pathname + (url.search || ''),
+                headers,
+                ...(bytes ? { 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());
+            return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json; charset=UTF-8', ...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 createInstagramTwinServer(options = {}) {
+    return serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createInstagramTwinFetch(options) });
+}

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

@@ -0,0 +1,52 @@
+import { type InstagramResponse } from './instagram-errors.js';
+export type InstagramRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    readOnly?: boolean;
+    occurredAt?: string;
+    root?: string;
+    /** The raw bytes of a rupload POST (instagram-server.ts reads them; the JSON adapter would corrupt binary). */
+    bytes?: Uint8Array;
+    /** Where this twin is reached (`twinPublicBase`). The rupload uri and media URLs are minted from it;
+     *  a direct handler call with none mints Meta's own hosts. */
+    publicBase?: string;
+};
+type Resource = Record<string, any>;
+/** The newest Graph API version (the references' "The latest version is: v26.0"). */
+export declare const LATEST_VERSION = "v26.0";
+/** The Graph API changelog's version table (read 2026-09-27): each version's release and expiry. A
+ *  version is usable until its expiry, judged at the request's (World) instant — its release date is
+ *  not held against a World whose clock is set back (an app's code names today's versions). */
+export declare const GRAPH_VERSIONS: ReadonlyArray<{
+    major: number;
+    released: string;
+    expires: string | null;
+}>;
+/** The versions usable at `nowMs`, oldest first. */
+export declare function usableVersions(nowMs: number): number[];
+/** Content Publishing guide: "100 API-published posts within a 24-hour moving period"; the IG User
+ *  Media Publish and Content Publishing Limit references: 50, "quota_total … (currently 50)". The twin
+ *  serves and enforces the references' 50 — the stricter figure, and the one the endpoint reports. */
+export declare const PUBLISH_QUOTA_TOTAL = 50;
+export declare const PUBLISH_QUOTA_DURATION_S = 86400;
+/** IG User Media: "An Instagram account can only create 400 containers within a rolling 24 hour period". */
+export declare const CONTAINER_QUOTA = 400;
+/** IG User Media, caption: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." */
+export declare const MAX_CAPTION_CHARS = 2200;
+export declare const MAX_HASHTAGS = 30;
+export declare const MAX_MENTIONS = 20;
+/** Meta's timestamp format: `2019-09-26T22:36:43+0000`. */
+export declare function igTimestamp(iso: string): string;
+/** The SHA-256 a token is held under — never the token itself. */
+export declare function tokenDigest(token: string): string;
+/** instagram.com's 11-character shortcode for a media id (a digest: stable for the id). */
+export declare function shortcodeFor(mediaId: string): string;
+/** Where a held Reel's bytes are served: instagram's CDN path shape under the twin's base. */
+export declare function reelVideoUrl(req: Pick<InstagramRequest, 'publicBase'>, sha256: string): string;
+/** A held media as the IG Media node answers it: its vendor fields, the URLs of the bytes the twin
+ *  holds, no `_` bookkeeping. */
+export declare function projectMedia(req: Pick<InstagramRequest, 'publicBase'>, all: Resource[], media: Resource): Record<string, unknown>;
+export declare function handleInstagramTwinRequest(req: InstagramRequest): Promise<InstagramResponse>;
+export {};