@volter/twin-instagram 0.1.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@volter/twin-instagram",
+  "version": "0.1.0",
+  "description": "Local Instagram twin (a professional account's Reels: resumable containers, the rupload upload, status_code, media_publish) with an instagram.com profile mirror, built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/instagram"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/instagram#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-instagram": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createInstagramTwinServer } from './instagram-server.ts';
+import { createInstagramMirrorServer } from './instagram-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve') {
+  const server = await createInstagramTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`instagram twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createInstagramMirrorServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`instagram mirror UI (instagram.com: log in, profile, Reels grid, Reel viewer) at ${s.url}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // Lazy — the conformance module is DEV-ONLY and must not be reachable from the runtime entrypoints.
+  const { checkInstagramConformance } = await import('./instagram-conformance.ts');
+  const report = await checkInstagramConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-instagram serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+export { GRAPH_VERSIONS, handleInstagramTwinRequest, igTimestamp, LATEST_VERSION, projectMedia, PUBLISH_QUOTA_TOTAL, reelVideoUrl, shortcodeFor, tokenDigest, usableVersions } from './instagram-twin.ts';
+export type { InstagramRequest } from './instagram-twin.ts';
+export type { InstagramResponse } from './instagram-errors.ts';
+export { createInstagramTwinFetch, createInstagramTwinServer, RANGE_CAP, type InstagramTwinFetchOptions } from './instagram-server.ts';
+export {
+  budgetedInstagramExecute,
+  containerParamsForVendor,
+  INSTAGRAM_VERSION,
+  InstagramCallError,
+  MAX_STATUS_WAIT_MS,
+  performInstagramAction,
+  performInstagramActionWithin,
+  STATUS_POLL_MS,
+  syncInstagramFromReal,
+  syncInstagramFromRemote,
+  UPLOAD_CHUNK_BYTES,
+  uploadReel,
+  uploadTarget,
+  waitForContainer,
+} from './instagram-connector.ts';
+export {
+  buildInstagramMirrorClient,
+  captionSegments,
+  compactCount,
+  createInstagramMirrorServer,
+  instagramMirrorHtml,
+  instagramMirrorStyles,
+  MIRROR_VERSION,
+  profileFromRead,
+  reelRoute,
+  tabReels,
+  timeAgo,
+} from './instagram-mirror-ui.ts';
+export type { IgRow, Segment } from './instagram-mirror-ui.ts';
+// The client-side rate budget the perform and refresh adapters charge (instagram-budget.ts says how the
+// numbers were chosen). The mechanism is the kernel's; these are this vendor's numbers.
+export {
+  INSTAGRAM_BUDGET_BURST_CEILING,
+  INSTAGRAM_BUDGET_CEILING,
+  INSTAGRAM_BUDGET_MAX_RETRY_AFTER_S,
+  INSTAGRAM_BUDGET_WINDOW_MS,
+  INSTAGRAM_CALL_WEIGHTS,
+  INSTAGRAM_RATE_BUDGET,
+  InstagramBudget,
+  InstagramBudgetError,
+  instagramBudgetPath,
+  instagramCallWeight,
+} from './instagram-budget.ts';
+
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performInstagramAction, syncInstagramFromRemote } from './instagram-connector.ts';
+import { INSTAGRAM_RATE_BUDGET as RATE_BUDGET } from './instagram-budget.ts';
+
+/**
+ * The Graph paths THIS pack serves, as a RegExp SOURCE for the descriptor's `hosts` path rule: an
+ * optional `/vNN.N` version, then `/me` or a numeric node (an IG User, an IG Media or an IG Container)
+ * with at most one of the edges modelled here — and the twin-only control prefix. ANCHORED, so
+ * `/{id}/insights` or `/{page-id}/feed` stays unclaimed and refuses loudly at the real vendor. A bare
+ * numeric node is claimed whatever it names (the path cannot tell an IG id from a Page's); a node the
+ * twin does not hold answers Meta's own "Unsupported get request".
+ */
+const GRAPH_PATHS = '^(?:/v\\d+\\.\\d+)?/(?:me|\\d{1,25})(?:/(?:media|media_publish|content_publishing_limit))?/?$|^/_twin/';
+
+export const pack: TwinPack = {
+  vendor: 'instagram',
+  // The SAME object instagram-budget.ts declares at module load — one source of truth.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a
+  // plugin — its wire, its tree, and its half of the real state system. Born on it.
+  protocol: '2',
+  archetype: 'crud',
+  bin: 'world-instagram',
+  resources: ['ig_user', 'media'],
+  specSource: 'Instagram Platform docs (developers.facebook.com/docs/instagram-platform, Graph API v26.0), read 2026-09-27: Content Publishing (incl. Resumable Upload Session and Reels), the IG User, IG User Media, IG Container, IG User Media Publish, IG Media and IG User Content Publishing Limit references, Error Codes; and the Graph API guides for Versioning, Handle Errors and Resumable Upload. Meta publishes no machine-readable spec for this surface.',
+  description: "Instagram twin — a professional account's Reels through the Graph API's content publishing flow (a resumable container, the rupload.facebook.com upload, the status_code lifecycle, media_publish), the account and media nodes, the publishing limit, and an instagram.com profile mirror with a Reels grid and a Reel viewer; everything else refuses by name.",
+  // An account's Reels barely move and Meta's limits are daily: hourly, and on demand.
+  refresh: { every: '1h', webhook: false, onDemand: { atMost: '60s' } },
+  stateSystem: { perform: performInstagramAction, refresh: syncInstagramFromRemote },
+  // The round trip: the professional account and the token the Facebook Login leg would have minted
+  // (the vendor has no create-from-nothing for either), then a Reels container on that account — staging
+  // the twin holds outside the log, as Meta holds it outside the account's media.
+  roundTrip: [
+    { method: 'POST', path: '/_twin/users', body: { id: '17841400000000001', username: 'round.trip', name: 'Round Trip', followers_count: 7 } },
+    { method: 'POST', path: '/_twin/tokens', body: { token: 'round-trip-token', user: '17841400000000001', permissions: ['instagram_basic', 'instagram_content_publish', 'pages_read_engagement'] } },
+    {
+      method: 'POST', path: '/v26.0/17841400000000001/media',
+      headers: { authorization: 'Bearer round-trip-token' },
+      body: { media_type: 'REELS', upload_type: 'resumable', caption: 'round trip' },
+    },
+  ],
+  parityOrigin: 'http://twin',
+  // the write handler and the refresh adapter store the same account shape (scripts/shape-parity.test.ts)
+  shapeParity: 'held',
+
+  // ADOPTION. Meta publishes no official JavaScript client for the Instagram Platform (the
+  // facebook-nodejs-business-sdk is the Marketing API's, and claiming it would attribute ads traffic
+  // to this twin). INSTAGRAM is the stem of INSTAGRAM_ACCESS_TOKEN / INSTAGRAM_USER_ID et al.
+  adoption: {
+    envStems: ['INSTAGRAM'],
+  },
+  // INTERCEPTION. graph.facebook.com (Facebook Login — the host the resumable upload is documented on)
+  // and graph.instagram.com (Instagram Login), both path-scoped to the nodes and edges above;
+  // rupload.facebook.com only for `/ig-api-upload/` — the upload host, which takes the SAME token, so
+  // the kernel executor sends the sealed credential there only because it is declared here as an exact
+  // host with this path; scontent.cdninstagram.com only for the CDN paths the twin mints for a Reel,
+  // its stand-in thumbnail and a profile picture.
+  hosts: [
+    { host: 'graph.facebook.com', pathPattern: GRAPH_PATHS },
+    { host: 'graph.instagram.com', pathPattern: GRAPH_PATHS },
+    { host: 'rupload.facebook.com', pathPattern: '^/ig-api-upload/' },
+    { host: 'scontent.cdninstagram.com', pathPattern: '^/(?:o1/v/t16/f2/m86/|v/t51\\.(?:71878-15|2885-19)/)' },
+  ],
+  endpointEnvNone: 'Meta ships no Instagram Platform client that reads a base-URL environment variable: apps call https://graph.facebook.com/<version>/… and the rupload host by constant, so a World reaches them through the hosts above; inventing an INSTAGRAM_BASE_URL the app never reads would report coverage the app does not have.',
+};
+
+registerPack(pack);

package/src/instagram-budget.ts

@@ -0,0 +1,130 @@
+// Instagram's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin typed
+// bindings the perform and refresh adapters use. The MECHANISM — the durable token-keyed ledger, the
+// rolling window, reserve-under-lock, the Retry-After / 429 cooldown, fail-CLOSED on a corrupt ledger
+// — lives ONCE in the kernel (`@volter/world-core` → rateBudget.ts).
+//
+// ── WHAT META PUBLISHES (developers.facebook.com/docs/instagram-platform, fetched 2026-09-27) ──
+//   • Content Publishing guide, "Rate Limit": "Instagram accounts are limited to 100 API-published
+//     posts within a 24-hour moving period … enforced on the POST /<IG_ID>/media_publish endpoint".
+//   • IG User Media Publish reference: "An Instagram professional account can only publish 50 posts
+//     within a 24 hour moving period"; the Content Publishing Limit reference reports quota_total
+//     "(currently 50)" over quota_duration 86400. THE STRICTER, 50, IS THE FIGURE THIS BUDGET KEEPS.
+//   • IG User Media reference: "An Instagram account can only create 400 containers within a rolling
+//     24 hour period".
+//   • The general Graph API call allowance is a Business Use Case formula over the account's
+//     impressions — no scalar a client can transcribe.
+//
+// ── HOW THE DECLARATION HOLDS THOSE DAILY FIGURES ──────────────────────────────────────────
+// The kernel's longest window is ONE HOUR, so a daily limit is spread over the day and rounded DOWN
+// (the YouTube pack's method): 250 weighted units per rolling hour, with
+//     a publish (POST /{id}/media_publish)   100 units → at most 2 an hour = 48 a day   ≤ 50
+//     a container (POST /{id}/media)          16 units → at most 15 an hour = 360 a day ≤ 400
+//     an upload POST to rupload (8 MiB chunk)   1 unit  (a 300 MB Reel is 36 chunks)
+//     a delete                                  8 units
+//     a read (status, node, list, limit)        1 unit
+//     anything else                             6 units
+// A client that spends this flat out for a whole day still lands under both documented limits.
+//
+// ── THE BURST SUB-CEILING ────────────────────────────────────────────────────────────────────
+// 180 units in any 60 s, SET BY THE PERFORM: one whole perform of the largest Reel inside a minute
+// (container 16 + 36 upload chunks + three status reads + publish 100 = 155) with room to spare. A burst
+// below that would refuse the publish of a Reel Meta finished quickly; the guard would be broken, not
+// tighter. The default weight (6, for a call no rule prices — the connector makes none) is then chosen so
+// the burst is 30 calls at it, the kernel fallback's own, so no burst anchor is claimed.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'instagram';
+
+/** Rolling window, in ms — the longest the kernel's ledger keeps (Meta's windows are 24 hours). */
+export const INSTAGRAM_BUDGET_WINDOW_MS = 60 * 60_000;
+/** Weighted units per window: the daily publish and container limits spread over the day, rounded down. */
+export const INSTAGRAM_BUDGET_CEILING = 250;
+/** Weighted units in any 60 s: 30 calls at the default weight (the fallback's burst), one whole Reel perform. */
+export const INSTAGRAM_BUDGET_BURST_CEILING = 180;
+/** Seconds. A Retry-After above this means the account or app is throttled for the day — fail loudly. */
+export const INSTAGRAM_BUDGET_MAX_RETRY_AFTER_S = 3600;
+
+export const INSTAGRAM_CALL_WEIGHTS = {
+  /** media_publish — the account speaking in public, 50 of them a day. */
+  publish: 100,
+  /** A container, 400 of them a day. */
+  container: 16,
+  /** A delete. */
+  delete: 8,
+  /** One rupload POST (an 8 MiB chunk at most). */
+  upload: 1,
+  /** A read: a container's status, a node, the media list, the publishing limit. */
+  read: 1,
+  /** Anything unnamed. */
+  other: 6,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Instagram-specific thing in the whole budget. */
+export const INSTAGRAM_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: INSTAGRAM_BUDGET_WINDOW_MS,
+  ceiling: INSTAGRAM_BUDGET_CEILING,
+  burstCeiling: INSTAGRAM_BUDGET_BURST_CEILING,
+  defaultWeight: INSTAGRAM_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: INSTAGRAM_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST (/v\\d+\\.\\d+)?/\\d+/media_publish$', weight: INSTAGRAM_CALL_WEIGHTS.publish },
+    { match: '^POST (/v\\d+\\.\\d+)?/\\d+/media$', weight: INSTAGRAM_CALL_WEIGHTS.container },
+    { match: '^DELETE (/v\\d+\\.\\d+)?/\\d+$', weight: INSTAGRAM_CALL_WEIGHTS.delete },
+    { match: '^POST (rupload\\.facebook\\.com)?/ig-api-upload/', weight: INSTAGRAM_CALL_WEIGHTS.upload },
+    { match: '^GET ', weight: INSTAGRAM_CALL_WEIGHTS.read },
+  ],
+  reason:
+    'Meta limits an Instagram professional account to 50 API-published posts in a 24-hour moving period (IG User Media '
+    + 'Publish and Content Publishing Limit references, "currently 50"; the Content Publishing guide says 100 — the '
+    + 'stricter 50 is kept) and to 400 containers in a rolling 24 hours (IG User Media reference), '
+    + 'developers.facebook.com/docs/instagram-platform, fetched 2026-09-27. The general call allowance is a Business Use '
+    + 'Case formula with no scalar. The daily figures are spread over the kernel\'s one-hour window and rounded down: '
+    + '250 units an hour, a publish 100 (2 an hour, 48 a day), a container 16 (15 an hour, 360 a day), a rupload POST '
+    + '(an 8 MiB chunk) 1, a delete 8, a read 1, anything else 6; a 180-unit burst per minute (30 calls at the default '
+    + "weight, the fallback's own) admits one whole perform of the largest Reel (155 units).",
+};
+
+declareRateBudget(VENDOR, INSTAGRAM_RATE_BUDGET);
+
+/**
+ * Price one call. `path` is the Graph path (`/v26.0/178…/media`) or, for the upload host, the absolute
+ * rupload URL — keyed `"<METHOD> <path>"` with the query split off (and the upload host kept in front
+ * of its path, so a twin's anchored `/ig-api-upload/…` and Meta's host price the same).
+ */
+export function instagramCallWeight(method: string, path: string): number {
+  let raw = path;
+  if (/^https?:\/\//i.test(raw)) { const u = new URL(raw); raw = `${u.hostname === 'rupload.facebook.com' ? u.hostname : ''}${u.pathname}${u.search}`; }
+  const at = raw.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(raw.slice(at + 1))) query[k] = v;
+  const bare = (at === -1 ? raw : raw.slice(0, at)).replace(/(.)\/+$/, '$1');
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/** Where this vendor's ledger lives: token-keyed and cwd-independent by default. */
+export function instagramBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+export type InstagramBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/** This vendor's budget — the kernel guard bound to this declaration. */
+export class InstagramBudget extends RateBudget {
+  constructor(opts: InstagramBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as InstagramBudgetError } from '@volter/world-core';
+export type InstagramBudgetReservation = RateBudgetReservation;
+export type InstagramBudgetSnapshot = RateBudgetSnapshot;