@volter/twin-linkedin 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@volter/twin-linkedin",
+  "version": "0.1.0",
+  "description": "Local LinkedIn twin (organization posts with image, video or article; the Images and Videos upload protocols; admin roles) with a linkedin.com company-page 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/linkedin"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/linkedin#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-linkedin": "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",
+    "linkedin-api-client": "^0.3.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 { createLinkedinTwinServer } from './linkedin-server.ts';
+import { createLinkedinMirrorServer } from './linkedin-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 createLinkedinTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`linkedin twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createLinkedinMirrorServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`linkedin mirror UI (linkedin.com: sign in, company page, posts, single post) 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 { checkLinkedinConformance } = await import('./linkedin-conformance.ts');
+  const report = await checkLinkedinConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-linkedin serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+export { ACTIVE_VERSIONS, handleLinkedinTwinRequest, projectPost, templateHashtags } from './linkedin-twin.ts';
+export type { LinkedinRequest } from './linkedin-twin.ts';
+export type { LinkedinResponse } from './linkedin-errors.ts';
+export { createLinkedinTwinFetch, createLinkedinTwinServer, type LinkedinTwinFetchOptions } from './linkedin-server.ts';
+export {
+  budgetedLinkedinExecute,
+  LINKEDIN_VERSION,
+  MAX_PROCESSING_WAIT_MS,
+  performLinkedinAction,
+  performLinkedinActionWithin,
+  postBodyForVendor,
+  syncLinkedinFromReal,
+  syncLinkedinFromRemote,
+  untemplateHashtags,
+  uploadVideoToVendor,
+} from './linkedin-connector.ts';
+export {
+  buildLinkedinMirrorClient,
+  commentarySegments,
+  createLinkedinMirrorServer,
+  followerLine,
+  linkedinMirrorHtml,
+  linkedinMirrorStyles,
+  mediaKind,
+  MIRROR_VERSION,
+  needsFold,
+  postRoute,
+  postsQuery,
+  relativeTime,
+  sourceHost,
+} from './linkedin-mirror-ui.ts';
+export type { LiRow, Segment } from './linkedin-mirror-ui.ts';
+// The client-side rate budget the perform and refresh adapters charge (linkedin-budget.ts says how the
+// numbers were chosen). The mechanism is the kernel's; these are this vendor's numbers.
+export {
+  LINKEDIN_BUDGET_BURST_CEILING,
+  LINKEDIN_BUDGET_CEILING,
+  LINKEDIN_BUDGET_MAX_RETRY_AFTER_S,
+  LINKEDIN_BUDGET_WINDOW_MS,
+  LINKEDIN_CALL_WEIGHTS,
+  LINKEDIN_RATE_BUDGET,
+  LinkedinBudget,
+  LinkedinBudgetError,
+  linkedinBudgetPath,
+  linkedinCallWeight,
+} from './linkedin-budget.ts';
+
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performLinkedinAction, syncLinkedinFromRemote } from './linkedin-connector.ts';
+import { LINKEDIN_RATE_BUDGET as RATE_BUDGET } from './linkedin-budget.ts';
+
+/**
+ * The api.linkedin.com paths THIS pack serves, as a RegExp SOURCE for the descriptor's `hosts` path
+ * rule: the versioned `/rest` resources an organization posts through, the OpenID userinfo, and the
+ * twin-only control prefix. ANCHORED, so `/rest/postsomething` stays unclaimed; everything else on
+ * api.linkedin.com (ads, analytics, comments, reactions, the legacy /v2 resources) refuses loudly at
+ * the real vendor rather than landing in a twin that cannot serve it.
+ */
+const API_PATHS = '^(?:/rest/(?:posts|images|videos|organizationAcls|organizations|organizationsLookup|networkSizes)(?:/[^/]+)?/?|/v2/userinfo/?)$|^/_twin/';
+
+export const pack: TwinPack = {
+  vendor: 'linkedin',
+  // The SAME object linkedin-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-linkedin',
+  resources: ['organization', 'member', 'organization_acl', 'token', 'post'],
+  specSource: 'LinkedIn Marketing API docs (learn.microsoft.com/linkedin, li-lms-2026-09), read 2026-09-26: Posts API + Post Schema, Images API, Videos API, Organization Access Control by Role, Organization Lookup (incl. networkSizes), Versioning, Error Responses, Rate Limiting; and Sign In with LinkedIn using OpenID Connect (/v2/userinfo). LinkedIn publishes no machine-readable spec for this surface.',
+  description: "LinkedIn twin — an organization's posts (commentary with one image, one video or an article) through the versioned Posts API, the Images and Videos upload protocols with signed upload URLs, the page's admin roles and follower count, and a linkedin.com company-page mirror; everything else refuses by name.",
+  // A page's posts barely move and LinkedIn's limits are daily: hourly, and on demand.
+  refresh: { every: '1h', webhook: false, onDemand: { atMost: '60s' } },
+  stateSystem: { perform: performLinkedinAction, refresh: syncLinkedinFromRemote },
+  // The round trip: the page, its admin, the admin's role and the token the OAuth leg would have
+  // minted (the vendor has no create-from-nothing for any of them), then a post — minted fresh from
+  // the tree on every send.
+  roundTrip: [
+    { method: 'POST', path: '/_twin/organizations', body: { id: '2414183', localizedName: 'Round Trip Co', vanityName: 'round-trip-co' } },
+    { method: 'POST', path: '/_twin/members', body: { id: 'roundTrip', localizedFirstName: 'Round', localizedLastName: 'Trip', email: 'round.trip@example.com' } },
+    { method: 'POST', path: '/_twin/organizationAcls', body: { organization: 'urn:li:organization:2414183', roleAssignee: 'urn:li:person:roundTrip', role: 'ADMINISTRATOR', state: 'APPROVED' } },
+    { method: 'POST', path: '/_twin/tokens', body: { token: 'round-trip-token', member: 'urn:li:person:roundTrip', scopes: ['w_organization_social', 'r_organization_social', 'rw_organization_admin'] } },
+    {
+      method: 'POST', path: '/rest/posts',
+      headers: { authorization: 'Bearer round-trip-token', 'linkedin-version': '202609', 'x-restli-protocol-version': '2.0.0' },
+      body: { author: 'urn:li:organization:2414183', commentary: 'round trip', visibility: 'PUBLIC', distribution: { feedDistribution: 'MAIN_FEED', targetEntities: [], thirdPartyDistributionChannels: [] }, lifecycleState: 'PUBLISHED', isReshareDisabledByAuthor: false },
+    },
+  ],
+  parityOrigin: 'http://twin',
+  // the write handler and the refresh adapter store the same shape (scripts/shape-parity.test.ts)
+  shapeParity: 'held',
+
+  // ADOPTION. `linkedin-api-client` is LinkedIn's own JavaScript client ("Official JavaScript client
+  // library for LinkedIn APIs", github.com/linkedin-developers/linkedin-api-js-client), and the
+  // Python client of the same repo family is `linkedin-api-client` on PyPI. LINKEDIN is the stem of
+  // LINKEDIN_ACCESS_TOKEN / LINKEDIN_CLIENT_ID et al.
+  adoption: {
+    sdks: ['linkedin-api-client'],
+    pypi: ['linkedin-api-client'],
+    envStems: ['LINKEDIN'],
+  },
+  // INTERCEPTION. api.linkedin.com for the API (path-scoped: this pack models one slice of it);
+  // www.linkedin.com only for the signed upload URLs (`/dms-uploads/`) the Images and Videos APIs
+  // return — never the site itself; media.licdn.com and dms.licdn.com for the image and video bytes
+  // an asset's downloadUrl names.
+  hosts: [
+    { host: 'api.linkedin.com', pathPattern: API_PATHS },
+    { host: 'www.linkedin.com', pathPattern: '^/dms-uploads/' },
+    { host: 'media.licdn.com', pathPattern: '^/dms/image/' },
+    { host: 'dms.licdn.com', pathPattern: '^/playlist/' },
+  ],
+  endpointEnvNone: "linkedin-api-client takes no base-URL environment variable (its RestliClient builds https://api.linkedin.com/rest URLs from a constant), so a World reaches it through the hosts above; inventing a LINKEDIN_BASE_URL the app never reads would report coverage the app does not have.",
+  browserRouting: { apiPathPrefix: '/rest/', loaderHost: 'https://api.linkedin.com' },
+};
+
+registerPack(pack);

package/src/linkedin-budget.ts

@@ -0,0 +1,108 @@
+// LinkedIn'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).
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// LinkedIn's published scheme, live-fetched for this build (learn.microsoft.com/linkedin/shared/
+// api-guide/concepts/rate-limits, fetched 2026-09-26): "Rate limits specify the maximum number of
+// API calls that can be made in a 24 hour period. These limits reset at midnight UTC every day",
+// per application and per member, "Rate limited requests will receive a 429 response", and
+// "Standard rate limits are not published in documentation" — each app reads its own in the
+// Developer Portal. So there is NO first-party figure to transcribe, and the declaration stays at
+// or under the kernel fallback: a one-hour window (the longest the kernel's rolling ledger keeps),
+// 600 weighted units in it, and a burst of 30 units a minute — the fallback's own burst, so no
+// VENDOR_BURST_ANCHOR is needed. A post or a delete (the org speaking in public) costs 5, the
+// upload control calls 2, every read 1, anything unnamed 2.
+//
+// WHAT IS NOT CHARGED. The part uploads a video perform sends to the signed www.linkedin.com
+// /dms-uploads URLs (presigned requests) are not API calls — the rate-limit page limits "API
+// requests", and those URLs are the upload service, carrying their own signature — so the budgeted
+// executor passes them through uncharged. Their number is bounded by construction instead: a
+// perform refuses a video over the feed's 500 MB (at most 125 parts of 4 MB) before initializing.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'linkedin';
+
+/** Rolling window, in ms — the longest the kernel's ledger keeps (LinkedIn's own window is a day). */
+export const LINKEDIN_BUDGET_WINDOW_MS = 60 * 60_000;
+/** Weighted units allowed inside one window: conservative, not transcribed (no figure is published). */
+export const LINKEDIN_BUDGET_CEILING = 600;
+/** Weighted units in any 60 s: the kernel fallback's 30, so no burst anchor is required. */
+export const LINKEDIN_BUDGET_BURST_CEILING = 30;
+/** Seconds. A Retry-After above this means the member or app is out for the day — fail loudly. */
+export const LINKEDIN_BUDGET_MAX_RETRY_AFTER_S = 3600;
+
+export const LINKEDIN_CALL_WEIGHTS = {
+  /** A post or its deletion — the organization speaking, in public. */
+  write: 5,
+  /** initializeUpload / finalizeUpload. */
+  upload: 2,
+  /** A read: a video's status, a finder page, an organization, the ACLs. */
+  read: 1,
+  /** Everything else on the vendor: priced above a read. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only LinkedIn-specific thing in the whole budget. */
+export const LINKEDIN_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: LINKEDIN_BUDGET_WINDOW_MS,
+  ceiling: LINKEDIN_BUDGET_CEILING,
+  burstCeiling: LINKEDIN_BUDGET_BURST_CEILING,
+  defaultWeight: LINKEDIN_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: LINKEDIN_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /rest/posts$', weight: LINKEDIN_CALL_WEIGHTS.write },
+    { match: '^DELETE /rest/posts/', weight: LINKEDIN_CALL_WEIGHTS.write },
+    { match: '^POST /rest/(videos|images)$', weight: LINKEDIN_CALL_WEIGHTS.upload },
+    { match: '^GET /rest/', weight: LINKEDIN_CALL_WEIGHTS.read },
+  ],
+  reason:
+    'LinkedIn limits API calls per application and per member over a 24-hour period reset at midnight UTC, '
+    + 'answers an exceeded limit with 429, and states "Standard rate limits are not published in documentation" '
+    + '(learn.microsoft.com/linkedin/shared/api-guide/concepts/rate-limits, fetched 2026-09-26). With no published '
+    + 'figure, this declaration stays at or under the kernel fallback rather than dressing a guess as a vendor fact: '
+    + '600 weighted units per rolling hour (the longest window the ledger keeps) and a 30-unit burst per minute (the '
+    + "fallback's own). A post or a delete costs 5, an upload initialize/finalize 2, a read 1, anything unnamed 2. The "
+    + 'signed /dms-uploads part PUTs are not API requests and are not charged; a perform bounds them to 125 parts.',
+};
+
+declareRateBudget(VENDOR, LINKEDIN_RATE_BUDGET);
+
+/** Price one call, keyed `"<METHOD> <path>"` with the query split off and the method upper-cased. */
+export function linkedinCallWeight(method: string, path: string): number {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/** Where this vendor's ledger lives: token-keyed and cwd-independent by default. */
+export function linkedinBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+export type LinkedinBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/** This vendor's budget — the kernel guard bound to this declaration. */
+export class LinkedinBudget extends RateBudget {
+  constructor(opts: LinkedinBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as LinkedinBudgetError } from '@volter/world-core';
+export type LinkedinBudgetReservation = RateBudgetReservation;
+export type LinkedinBudgetSnapshot = RateBudgetSnapshot;