integration.social-tracking-runtime
Provider-neutral social analytics tracking runtime with Postgres persistence and public metadata fallback.
@lssm-tech/integration.social-tracking-runtimebun add @lssm-tech/integration.social-tracking-runtimeManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Provider-neutral orchestration for continuous creator and content analytics on YouTube, TikTok, Instagram, and X.
The runtime selects an available source in this order: official API, approved connector, then the optional public metadata fallback. It discovers creator content, records idempotent 30-minute snapshots, builds deterministic UTC hourly/daily/weekly rollups, exports analytics as CSV, deduplicates webhooks, and applies configurable retention.
import { createSocialTrackingService, PrioritySocialTrackingSourceRegistry } from "@lssm-tech/integration.social-tracking-runtime";
import { createPostgresSocialTrackingStore, migratePostgresSocialTrackingStore } from "@lssm-tech/integration.social-tracking-runtime/postgres";
await migratePostgresSocialTrackingStore(database);
const store = createPostgresSocialTrackingStore({ database });
const registry = new PrioritySocialTrackingSourceRegistry(sources);
const tracking = createSocialTrackingService({ registry, store });
await tracking.startCreatorTracking({
consumerKey: "analytics-dashboard",
context,
idempotencyKey: "onboard:youtube:creator-123",
platform: "youtube",
selector: { id: "creator-123" },
});The public-metadata entrypoint exposes a hardened yt-dlp runner and metadata-only source. Only HTTPS URLs for supported public platform hosts are accepted; credentials, cookies, downloads, playlists, and shell evaluation are disabled.
For TikTok, Instagram, and X standalone content tracking, pass the canonical HTTPS content URL as contentId. Opaque non-YouTube ids are intentionally not expanded into guessed URLs.
Postgres persistence treats (tenantId, workspaceId) as an inseparable scope. Callers must migrate once, then supply scope on every read, collection, retention, and analytics operation.
Tracking lifecycle starts require a caller-owned idempotency key. Replaying the same key within a tenant, workspace, and consumer returns the original config without repeating provider discovery. Analytics snapshots, rollups, queries, exports, and retention are partitioned by consumerKey.
Retention resolves in deterministic precedence order: runtime defaults, then the optional tenant/platform/consumer resolver, then explicit start-call overrides. Weekly rollups remain indefinite unless weeklyDays is configured by the resolver or call.
Rollups record measurement coverage: samples without a usable value are counted but never become zero, partial subtotals are never complete, and the CSV export neutralises spreadsheet formulas and appends an availability column.
The account-capabilities entrypoint reports per-account capability state; only read_metrics can be available, direct_publish is always manual_only, and no state authorizes posting or payment.
Measurement definitions and the account capability matrix are owned by @lssm-tech/lib.contracts-integrations/integrations/social/tracking-measurement-definitions and …/tracking-account-capabilities; the runtime re-exports them by identity.
The publishing-checklist entrypoint evaluates the pre-publication checklist for creator-published collaborations. Every evaluation is a manual handoff (directPublish: 'manual_only') and grants no posting, publishing or payment authority; publishingAccountFact reads the account from the capability matrix, and only an available account is a provider-qualified proof path.
TS-01-P-SOCIAL
LinkedIn is official-API only; public-metadata normalization refuses LinkedIn URLs (no scraping).
TS-01-RESULTS
./csv-import parses a reviewed results CSV (parseResultsCsv, refusing with ResultsCsvImportError) and reads back the existing analytics export (parseAnalyticsCsv, the inverse of analyticsSeriesToCsv). Hosts pass parseResultsCsv to MarketingResultService for the result import operation.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
2 declarations
@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.schemaworkspace:^
Read the package manual ↗
Declared capabilities
Provider-neutral social analytics tracking runtime with Postgres persistence and public metadata fallback.
Scripts
buildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typescleanrimraf dist .turbolint:checknode ../../../scripts/biome.cjs check .lint:fixnode ../../../scripts/biome.cjs check --write .prebuildcontractspec-bun-build prebuildtestbun testtypechecktsgo --noEmit