@lssm/integration.provider-linkedin

Official-API-only LinkedIn adapters for ContractSpec verticals.

Supported surfaces

• typed LinkedIn post drafts and explicit validation;
• OAuth 2.0 authorization-code connection with state, PKCE, refresh, and secret-reference-only persistence;
• member, organization, and first-degree connection reads;
• posts, comments, replies, reactions, and community analytics;
• invitations, conversations, inbox messages, replies, and outreach;
• Sales Navigator lead/account search, CRM association, and evidence-backed employment validation;
• advertising accounts, campaigns, creatives, audiences, and reporting;
• webhook subscription, challenge, authenticity, normalization, deduplication, replay-window enforcement, tenant binding, checkpoints, and backfill;
• delta/cursor imports for profiles, organizations, connections, and lead responses;
• host-neutral OAuth callback and webhook adapters plus a provider-neutral Communication OS channel adapter.

The package models all of these surfaces, but it does not pretend that a LinkedIn product has been granted. Partner-restricted operations stay approval_required until the exact product, scopes, actor/resource roles, API version, operation, and effect class are approved and certified. Read certification never elevates a write or spend operation.

Narrow imports

import { LinkedInOAuth } from "@lssm/integration.provider-linkedin/oauth";
import { migrateLinkedInLegacyOAuth } from "@lssm/integration.provider-linkedin/migration";
import { LinkedInCommunicationAdapter } from "@lssm/integration.provider-linkedin/communication-os";
import { LinkedInSalesAdapter } from "@lssm/integration.provider-linkedin/sales";
import { LinkedInAdvertisingAdapter } from "@lssm/integration.provider-linkedin/advertising";
import { LinkedInCommunicationChannelAdapter } from "@lssm/integration.provider-linkedin/channel";
import { LinkedInOAuthHostAdapter, LinkedInWebhookHostAdapter } from "@lssm/integration.provider-linkedin/host";
import { DefaultLinkedInResponseNormalizer } from "@lssm/integration.provider-linkedin/normalizers";
import { LinkedInSyncAdapter } from "@lssm/integration.provider-linkedin/sync";

The corresponding stable ports and models are available from @lssm/lib.contracts-integrations/integrations/linkedin.

Safety boundary

• No scraping, cookie authentication, browser automation, or undocumented endpoint is provided.
• Tokens are resolved through LinkedInTokenSource; serialized connections contain only LinkedInCredentialReference.
• OAuth redirect URIs and webhook callback URLs use exact HTTPS allowlists.
• Provider JSON passes the concrete DefaultLinkedInResponseNormalizer (or an explicitly injected version-aware replacement); raw provider DTOs are never returned as contract records.
• Invitations, messages, community mutations, posts, campaigns, and spend require authority, approval, and idempotency references.
• Default tests use fixtures and mocked HTTP. Live certification is opt-in and must use approved non-production resources without real outreach or spend.

Approved partner endpoints are installation configuration. When an endpoint is not configured, the adapter returns approval_required before network dispatch.

Transport safety: LinkedInClient snapshots and freezes requests before authorization, checks stable operation/effect/authority bindings, and rejects reserved header overrides. Writes have one attempt even when an idempotency reference is present. Only GETs use bounded retries; redirects are rejected, requests have bounded timeouts and response bodies are capped at 5 MB. HTTP errors do not expose raw provider error messages.

An optional third response-decoder argument supplies { status, resourceId }, preserving x-restli-id for explicit handling of bodyless creation responses. This does not fabricate a published-post DTO or certify a native publishing workflow. Existing decoders remain compatible. timeoutMs is configurable from 1 to 120000; maxAttempts from 1 to 10.

./native-publication exposes LinkedInNativePublicationProvider for the scoped V2 social port. A required authorized material loader binds tenant/account/revision/digest and the member or organization author. It compiles real Posts API bodies for text and pre-uploaded image/video/document/article/multi-image content. Ready assets and rights are host checks.

Creation is accepted only with a valid 201 post URN. A separately authorized GET confirms the exact post and author in PUBLISHED state. Ambiguous creates are never retried. Configure this adapter in publicationPorts.providersV2.linkedin when composing marketing scheduling. The generic legacy draft-based adapter is unchanged. Upload processing, X publication and live account qualification remain separate work.

Protocol reference: LinkedIn Posts API.

The native publisher rejects unresolved policy obligations other than reason annotations. Session-only, redaction and reevaluation constraints must be resolved through the governing workflow before a publishable revision reaches this adapter; they are never ignored.

Native media protocol

./media exports createLinkedInMediaProvider, which shares one API version, access policy and secret source across image/video initialization, binary transfer, video finalization and media status reads. Upload/read use their own capability IDs and four operation keys; post-publication certification does not authorize them. Member and organization grants retain distinct scopes and roles. Existing provider implementations may omit these optional methods.

Initialization validates contiguous native byte ranges and returns transient upload capabilities. Keep sessions (signed URLs and upload tokens) in a private vault, never ordinary job/event payloads. Transfer verifies the expected SHA-256, sends one bounded PUT to the official LinkedIn upload origin without redirects/retries, and retains ETags for ordered video finalization. Reads verify native identity/owner before projecting AVAILABLE. Captions/thumbnails are not requested by this initializer.

These are protocol primitives, not a durable worker. Callers must claim each write before invocation, preserve ambiguous outcomes, enforce session expiry and recheck rights. Durable Marketing Operations session orchestration and live qualification are still required. Official references: Images API and Videos API.

./media-job now exports LinkedInMediaJobRuntime. Supply SqlLinkedInMediaJobStore, the native protocol provider, current authority, immutable asset-range reads and exact transport recovery receipts. Bounded run(plan, maxSteps) calls retain claimed effects and resume remaining work. Image transfers proceed to processing; video transfers preserve ordered ETags for native finalization.

./media-session-vault reuses the existing SecretProvider. References are bound to tenant/workspace/account/job/request and content digest, and reads require the exact returned secret version. Signed URLs and upload tokens never enter ordinary SQL job history. Session expiry blocks pending transfers; it does not expire ready native assets. Use linkedInUploadedMedia only after readiness, and recheck current publication rights. Hosted worker installation, live qualification, captions and thumbnails remain pending.

native-withdrawal implements the content withdrawal port using post-management authority and the official DELETE endpoint. It binds the revoked use to a historical owned post and requires native 204 confirmation. Reconciliation reads an exact job/post-bound recorded deletion receipt; a bare 404 does not prove deletion. Use with the durable ContentWithdrawalWorker. Live account qualification remains required.