@lssm/lib.contracts-integrations 9.0.1

package/dist/integrations/secrets/scaleway-secret-manager.js

@@ -0,0 +1,2 @@
+// @bun
+import{Buffer as l}from"buffer";import{Buffer as f}from"buffer";class i extends Error{provider;reference;code;cause;constructor(e){super(e.message);this.name="SecretProviderError",this.provider=e.provider,this.reference=e.reference,this.code=e.code??"UNKNOWN",this.cause=e.cause}}function S(e){if(!e)throw new i({message:"Secret reference cannot be empty",provider:"unknown",reference:e,code:"INVALID"});let[r,t]=e.split("://");if(!r||!t)throw new i({message:`Invalid secret reference: ${e}`,provider:"unknown",reference:e,code:"INVALID"});let n=t.indexOf("?");if(n===-1)return{provider:r,path:t};let o=t.slice(0,n),s=t.slice(n+1),c=Object.fromEntries(s.split("&").filter(Boolean).map((a)=>{let[u,h]=a.split("="),m=u??"",w=h??"";return[decodeURIComponent(m),decodeURIComponent(w)]}));return{provider:r,path:o,extras:c}}function p(e){if(e.data instanceof Uint8Array)return e.data;if(e.encoding==="base64")return f.from(e.data,"base64");if(e.encoding==="binary")return f.from(e.data,"binary");return f.from(e.data,"utf-8")}var g=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;class v{id="scaleway-secret-manager";token;defaultRegion;defaultProjectId;baseUrl;fetchFn;constructor(e={}){this.token=e.token??process.env.SCW_SECRET_KEY??process.env.SCALEWAY_SECRET_KEY??"",this.defaultRegion=e.defaultRegion??process.env.SCW_DEFAULT_REGION??process.env.SCW_REGION,this.defaultProjectId=e.defaultProjectId??process.env.SCW_DEFAULT_PROJECT_ID??process.env.SCW_PROJECT_ID,this.baseUrl=e.baseUrl??"https://api.scaleway.com",this.fetchFn=e.fetch??fetch}canHandle(e){try{let r=S(e);return r.provider==="scw"&&(r.path==="secret-manager"||r.path.startsWith("secret-manager/"))}catch{return!1}}async getSecret(e,r){let t=this.parseReference(e);if(!this.token)throw new i({message:"Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",provider:this.id,reference:e,code:"FORBIDDEN"});if(!g.test(t.secretIdOrName))throw new i({message:"Scaleway getSecret requires a secretId (uuid) reference, not a secret name.",provider:this.id,reference:e,code:"INVALID"});let n=r?.version??t.revision??"latest",o=`${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(t.region)}/secrets/${encodeURIComponent(t.secretIdOrName)}/versions/${encodeURIComponent(n)}/access`,s=await this.fetchFn(o,{method:"GET",headers:{"X-Auth-Token":this.token}});if(!s.ok)throw await d({response:s,provider:this.id,reference:e,operation:"getSecret"});let c=await s.json(),a=y(c);return{data:l.from(a,"base64"),version:n,metadata:{region:t.region,secretId:t.secretIdOrName},retrievedAt:new Date}}async setSecret(e,r){let t=this.parseReference(e);if(!this.token)throw new i({message:"Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",provider:this.id,reference:e,code:"FORBIDDEN"});let n=p(r),o=l.from(n).toString("base64"),s=g.test(t.secretIdOrName)?t.secretIdOrName:await this.createSecret({region:t.region,name:t.secretIdOrName,reference:e}),c=await this.createSecretVersion({region:t.region,secretId:s,dataB64:o,reference:e});return{reference:this.buildReference(t.region,s,{version:c}),version:c}}async rotateSecret(e,r){return this.setSecret(e,r)}async deleteSecret(e){let r=this.parseReference(e);if(!this.token)throw new i({message:"Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",provider:this.id,reference:e,code:"FORBIDDEN"});if(!g.test(r.secretIdOrName))throw new i({message:"Scaleway deleteSecret requires a secretId (uuid) reference, not a secret name.",provider:this.id,reference:e,code:"INVALID"});let t=`${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(r.region)}/secrets/${encodeURIComponent(r.secretIdOrName)}`,n=await this.fetchFn(t,{method:"DELETE",headers:{"X-Auth-Token":this.token}});if(!n.ok)throw await d({response:n,provider:this.id,reference:e,operation:"deleteSecret"})}parseReference(e){let r=S(e);if(r.provider!=="scw")throw new i({message:`Unsupported secret provider: ${r.provider}`,provider:this.id,reference:e,code:"INVALID"});let t=r.path.split("/").filter(Boolean);if(t.length<2||t[0]!=="secret-manager")throw new i({message:"Expected secret reference format scw://secret-manager/{region}/{secretIdOrName}[?version=...]",provider:this.id,reference:e,code:"INVALID"});let n=t[1]??this.defaultRegion;if(!n)throw new i({message:"Scaleway region must be provided either in reference (scw://secret-manager/{region}/...) or via SCW_DEFAULT_REGION/SCW_REGION.",provider:this.id,reference:e,code:"INVALID"});let o=t.slice(2).join("/");if(!o)throw new i({message:`Unable to resolve secret id/name from reference "${r.path}"`,provider:this.id,reference:e,code:"INVALID"});return{region:n,secretIdOrName:o,revision:r.extras?.version}}async createSecret(e){let r=this.defaultProjectId;if(!r)throw new i({message:"Scaleway project id is required to create secrets by name (set SCW_DEFAULT_PROJECT_ID/SCW_PROJECT_ID).",provider:this.id,reference:e.reference,code:"INVALID"});let t=`${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(e.region)}/secrets`,n=await this.fetchFn(t,{method:"POST",headers:{"Content-Type":"application/json","X-Auth-Token":this.token},body:JSON.stringify({name:e.name,project_id:r})});if(!n.ok)throw await d({response:n,provider:this.id,reference:e.reference,operation:"createSecret"});let o=await n.json();return R(o)}async createSecretVersion(e){let r=`${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(e.region)}/secrets/${encodeURIComponent(e.secretId)}/versions`,t=await this.fetchFn(r,{method:"POST",headers:{"Content-Type":"application/json","X-Auth-Token":this.token},body:JSON.stringify({data:e.dataB64})});if(!t.ok)throw await d({response:t,provider:this.id,reference:e.reference,operation:"createSecretVersion"});let n=await t.json();return I(n)??"latest"}buildReference(e,r,t){let n=`scw://secret-manager/${e}/${r}`,o=t?Object.entries(t).filter(([,s])=>Boolean(s)).map(([s,c])=>`${encodeURIComponent(s)}=${encodeURIComponent(c)}`).join("&"):"";return o?`${n}?${o}`:n}}function y(e){if(!e||typeof e!=="object")throw Error("Invalid scaleway secret payload");let r=e;if(typeof r.data==="string"&&r.data)return r.data;throw Error("Scaleway secret payload is missing data")}function R(e){if(!e||typeof e!=="object")throw Error("Invalid scaleway createSecret payload");let r=e;if(typeof r.id==="string"&&r.id)return r.id;throw Error("Scaleway createSecret response is missing id")}function I(e){if(!e||typeof e!=="object")return;let r=e;if(typeof r.revision==="number")return String(r.revision);if(typeof r.revision==="string"&&r.revision)return r.revision;if(typeof r.id==="string"&&r.id)return r.id;return}async function d(e){let{response:r,provider:t,reference:n,operation:o}=e,s=r.status===404?"NOT_FOUND":r.status===401||r.status===403?"FORBIDDEN":r.status>=400&&r.status<500?"INVALID":"UNKNOWN",c=await E(r),a=c?`Scaleway Secret Manager ${o} failed (${r.status}): ${c}`:`Scaleway Secret Manager ${o} failed (${r.status})`;return new i({message:a,provider:t,reference:n,code:s})}async function E(e){try{let t=(await e.text()).trim();return t.length?t:void 0}catch{return}}export{v as ScalewaySecretManagerProvider};

package/dist/integrations/secrets-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Secret Provider types for integrations
+ * These are core type definitions that don't require runtime dependencies.
+ */
+export interface SecretValue {
+    data: Uint8Array;
+    version?: string;
+    metadata?: Record<string, string>;
+}
+export interface SecretProvider {
+    id: string;
+    canHandle(reference: string): boolean;
+    getSecret(reference: string): Promise<SecretValue>;
+}

package/dist/integrations/secrets-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/social/index.d.ts

@@ -0,0 +1,7 @@
+export * from './instagram.js';
+export * from './models.js';
+export * from './provider.js';
+export * from './tracking-models.js';
+export * from './tracking-provider.js';
+export * from './tracking-store.js';
+export * from './x.js';

package/dist/integrations/social/index.js

@@ -0,0 +1,2 @@
+// @bun
+var n=["profile.get","content.get","content.list","content.sync","webhook.event.normalize"],a=["analytics.query","content.track","creator.track"];class t extends Error{code;retryable;providerStatus;constructor(i,e,r=!1,o){super(e);this.code=i;this.retryable=r;this.providerStatus=o;this.name="SocialProviderError"}}var l={thirtyMinuteDays:90,hourlyDays:548,dailyDays:1826};export{l as DEFAULT_SOCIAL_RETENTION_POLICY,n as SOCIAL_READ_OPERATION_SUFFIXES,a as SOCIAL_TRACKING_OPERATION_SUFFIXES,t as SocialProviderError};

package/dist/integrations/social/instagram.d.ts

@@ -0,0 +1,86 @@
+export type InstagramCapabilityId = 'instagram.profile.read' | 'instagram.content.read';
+export interface InstagramCapabilityDecision {
+    capability: InstagramCapabilityId;
+    state: 'approval_required' | 'available' | 'disabled' | 'unavailable';
+    reason: string;
+}
+export interface InstagramInstallation {
+    capabilities: readonly InstagramCapabilityDecision[];
+}
+export interface InstagramRequestContext {
+    capability: InstagramCapabilityId;
+    connectionId: string;
+    installationId: string;
+    requestId: string;
+    tenantId: string;
+    workspaceId: string;
+}
+export interface InstagramProfileRecord {
+    biography?: string;
+    followersCount?: number;
+    followsCount?: number;
+    id: string;
+    mediaCount?: number;
+    name?: string;
+    native: Record<string, unknown>;
+    profilePictureUrl?: string;
+    username: string;
+    website?: string;
+}
+export interface InstagramContentRecord {
+    caption?: string;
+    id: string;
+    kind: 'album' | 'image' | 'reel' | 'short' | 'story' | 'video';
+    likeCount?: number;
+    commentCount?: number;
+    mediaUrl?: string;
+    native: Record<string, unknown>;
+    permalink?: string;
+    publishedAt?: string;
+    thumbnailUrl?: string;
+    username?: string;
+    viewCount?: number;
+}
+export interface InstagramPageInfo {
+    cursor?: string;
+    hasMore: boolean;
+}
+export interface InstagramOperationResult<T> {
+    capability: InstagramCapabilityDecision;
+    output: T;
+    providerRequestId?: string;
+    requestId: string;
+}
+export interface InstagramSocialProvider {
+    discoverCapabilities(installation: InstagramInstallation, requested?: readonly InstagramCapabilityId[]): Promise<readonly InstagramCapabilityDecision[]>;
+    getContent(request: {
+        context: InstagramRequestContext;
+        effect: 'read';
+        input: {
+            id: string;
+        };
+        operationKey: 'instagram.content.get';
+    }): Promise<InstagramOperationResult<InstagramContentRecord>>;
+    getProfile(request: {
+        context: InstagramRequestContext;
+        effect: 'read';
+        input: {
+            id?: string;
+            username?: string;
+        };
+        operationKey: 'instagram.profile.get';
+    }): Promise<InstagramOperationResult<InstagramProfileRecord>>;
+    listContent(request: {
+        context: InstagramRequestContext;
+        effect: 'read';
+        input: {
+            cursor?: string;
+            limit?: number;
+            userId?: string;
+        };
+        operationKey: 'instagram.content.list';
+    }): Promise<InstagramOperationResult<{
+        items: readonly InstagramContentRecord[];
+        page: InstagramPageInfo;
+    }>>;
+}

package/dist/integrations/social/instagram.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/social/models.d.ts

@@ -0,0 +1,107 @@
+/** Official connected-account social platform records. */
+export type SocialPlatform = 'youtube' | 'tiktok' | 'instagram' | 'x';
+export interface SocialEvidence {
+    platform: SocialPlatform;
+    providerApiVersion: string;
+    capturedAt: string;
+    providerRequestId?: string;
+    connectionId: string;
+}
+export interface SocialPage {
+    cursor?: string;
+    hasMore: boolean;
+}
+export interface YouTubeProfile {
+    platform: 'youtube';
+    id: string;
+    title: string;
+    handle?: string;
+    description?: string;
+    thumbnailUrl?: string;
+    evidence: SocialEvidence;
+}
+export interface TikTokProfile {
+    platform: 'tiktok';
+    openId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    profileDeepLink?: string;
+    bioDescription?: string;
+    evidence: SocialEvidence;
+}
+export interface InstagramProfile {
+    platform: 'instagram';
+    id: string;
+    username: string;
+    name?: string;
+    biography?: string;
+    profilePictureUrl?: string;
+    accountType: 'business' | 'creator';
+    evidence: SocialEvidence;
+}
+export interface XProfile {
+    platform: 'x';
+    id: string;
+    username: string;
+    name: string;
+    description?: string;
+    profileImageUrl?: string;
+    evidence: SocialEvidence;
+}
+export type SocialProfileRecord = YouTubeProfile | TikTokProfile | InstagramProfile | XProfile;
+export interface YouTubeContent {
+    platform: 'youtube';
+    id: string;
+    kind: 'video' | 'short';
+    channelId: string;
+    title: string;
+    description?: string;
+    publishedAt?: string;
+    thumbnailUrl?: string;
+    evidence: SocialEvidence;
+}
+export interface TikTokContent {
+    platform: 'tiktok';
+    id: string;
+    title?: string;
+    coverImageUrl?: string;
+    shareUrl?: string;
+    createTime?: string;
+    evidence: SocialEvidence;
+}
+export interface InstagramContent {
+    platform: 'instagram';
+    id: string;
+    mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM';
+    caption?: string;
+    mediaUrl?: string;
+    permalink?: string;
+    timestamp?: string;
+    evidence: SocialEvidence;
+}
+export interface XContent {
+    platform: 'x';
+    id: string;
+    text: string;
+    authorId: string;
+    createdAt?: string;
+    conversationId?: string;
+    evidence: SocialEvidence;
+}
+export type SocialContentRecord = YouTubeContent | TikTokContent | InstagramContent | XContent;
+export interface SocialSyncCursor {
+    platform: SocialPlatform;
+    connectionId: string;
+    cursor?: string;
+    watermark?: string;
+    checkpointId?: string;
+}
+export interface SocialWebhookEvent {
+    platform: SocialPlatform;
+    eventId: string;
+    eventType: string;
+    occurredAt: string;
+    connectionId: string;
+    rawPayloadHash: string;
+    contentId?: string;
+}

package/dist/integrations/social/models.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/social/provider.d.ts

@@ -0,0 +1,46 @@
+import type { SocialContentRecord, SocialPage, SocialPlatform, SocialProfileRecord, SocialSyncCursor, SocialWebhookEvent } from './models.js';
+export declare const SOCIAL_READ_OPERATION_SUFFIXES: readonly ['profile.get', 'content.get', 'content.list', 'content.sync', 'webhook.event.normalize'];
+export declare const SOCIAL_TRACKING_OPERATION_SUFFIXES: readonly ['analytics.query', 'content.track', 'creator.track'];
+export type SocialReadOperationSuffix = (typeof SOCIAL_READ_OPERATION_SUFFIXES)[number];
+export type SocialReadOperationKey = `${SocialPlatform}.${SocialReadOperationSuffix}`;
+export type SocialTrackingOperationSuffix = (typeof SOCIAL_TRACKING_OPERATION_SUFFIXES)[number];
+export type SocialTrackingOperationKey = `${SocialPlatform}.${SocialTrackingOperationSuffix}`;
+export interface SocialProviderContext {
+    tenantId: string;
+    workspaceId: string;
+    connectionId: string;
+    credentialRefId: string;
+    requestId: string;
+    correlationId: string;
+}
+export interface GetSocialContentInput {
+    id: string;
+}
+export interface ListSocialContentInput {
+    cursor?: string;
+    limit?: number;
+}
+export interface SocialContentPage<T extends SocialContentRecord> {
+    items: readonly T[];
+    page: SocialPage;
+}
+export interface SocialSyncResult<T extends SocialContentRecord> {
+    items: readonly T[];
+    cursor: SocialSyncCursor;
+    backfillRequired: boolean;
+}
+export interface SocialProvider<TProfile extends SocialProfileRecord, TContent extends SocialContentRecord> {
+    readonly platform: TProfile['platform'];
+    getProfile(context: SocialProviderContext): Promise<TProfile>;
+    getContent(context: SocialProviderContext, input: GetSocialContentInput): Promise<TContent>;
+    listContent(context: SocialProviderContext, input: ListSocialContentInput): Promise<SocialContentPage<TContent>>;
+    syncContent(context: SocialProviderContext, cursor: SocialSyncCursor): Promise<SocialSyncResult<TContent>>;
+    normalizeWebhook?(context: SocialProviderContext, rawBody: Uint8Array, headers: Readonly<Record<string, string | undefined>>): Promise<SocialWebhookEvent>;
+}
+export type SocialProviderErrorCode = 'approval_required' | 'scope_missing' | 'account_type_unsupported' | 'connected_account_required' | 'vendor_mcp_unavailable' | 'rate_limited' | 'invalid_response' | 'dependency_failure';
+export declare class SocialProviderError extends Error {
+    readonly code: SocialProviderErrorCode;
+    readonly retryable: boolean;
+    readonly providerStatus?: number | undefined;
+    constructor(code: SocialProviderErrorCode, message: string, retryable?: boolean, providerStatus?: number | undefined);
+}

package/dist/integrations/social/provider.js

@@ -0,0 +1,2 @@
+// @bun
+var i=["profile.get","content.get","content.list","content.sync","webhook.event.normalize"],a=["analytics.query","content.track","creator.track"];class o extends Error{code;retryable;providerStatus;constructor(t,e,r=!1,n){super(e);this.code=t;this.retryable=r;this.providerStatus=n;this.name="SocialProviderError"}}export{i as SOCIAL_READ_OPERATION_SUFFIXES,a as SOCIAL_TRACKING_OPERATION_SUFFIXES,o as SocialProviderError};

package/dist/integrations/social/social.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/integrations/social/tracking-models.d.ts

@@ -0,0 +1,153 @@
+import type { SocialPlatform } from './models.js';
+export type SocialTrackingAccess = 'connected' | 'public';
+export type SocialTrackingSourceKind = 'official_api' | 'approved_connector' | 'public_fallback';
+export type SocialTrackingSubjectKind = 'creator' | 'content';
+export type SocialMetricSemantics = 'counter' | 'gauge' | 'period';
+export type SocialMetricUnit = 'count' | 'milliseconds' | 'minutes' | 'percentage' | 'seconds';
+export type SocialMetricKey = 'comments' | 'engagements' | 'followers' | 'following' | 'likes' | 'media' | 'posts' | 'reactions' | 'reposts' | 'saves' | 'shares' | 'subscribers' | 'views' | `provider.${string}`;
+export interface SocialTrackingScope {
+    tenantId: string;
+    workspaceId: string;
+}
+export interface SocialTrackingEvidence {
+    access: SocialTrackingAccess;
+    capturedAt: string;
+    connectionId?: string;
+    providerApiVersion?: string;
+    providerRequestId?: string;
+    rawPayloadHash?: string;
+    source: SocialTrackingSourceKind;
+}
+export interface SocialMetricValue {
+    key: SocialMetricKey;
+    nativeKey?: string;
+    semantics: SocialMetricSemantics;
+    unit: SocialMetricUnit;
+    value: number;
+}
+export interface SocialCreator {
+    avatarUrl?: string;
+    biography?: string;
+    canonicalUrl?: string;
+    displayName: string;
+    handle?: string;
+    id: string;
+    metrics: readonly SocialMetricValue[];
+    platform: SocialPlatform;
+    evidence: SocialTrackingEvidence;
+}
+export type SocialContentKind = 'album' | 'image' | 'post' | 'reel' | 'reply' | 'repost' | 'short' | 'story' | 'thread' | 'video';
+export interface SocialContent {
+    availability?: 'available' | 'deleted' | 'private' | 'restricted' | 'unavailable';
+    caption?: string;
+    canonicalUrl?: string;
+    creatorId: string;
+    durationSeconds?: number;
+    deletedAt?: string;
+    id: string;
+    kind: SocialContentKind;
+    mediaUrl?: string;
+    metrics: readonly SocialMetricValue[];
+    platform: SocialPlatform;
+    publishedAt?: string;
+    thumbnailUrl?: string;
+    title?: string;
+    evidence: SocialTrackingEvidence;
+}
+export interface SocialTrackingSelector {
+    handle?: string;
+    id?: string;
+    url?: string;
+}
+export interface SocialTrackingTarget {
+    creatorId?: string;
+    id: string;
+    platform: SocialPlatform;
+    providerId: string;
+    sourceLocator?: string;
+    subjectKind: SocialTrackingSubjectKind;
+}
+export type SocialTrackingStatus = 'active' | 'paused' | 'rate_limited' | 'source_unavailable' | 'stopped';
+export interface SocialRetentionPolicy {
+    dailyDays: number;
+    hourlyDays: number;
+    thirtyMinuteDays: number;
+    weeklyDays?: number;
+}
+export declare const DEFAULT_SOCIAL_RETENTION_POLICY: SocialRetentionPolicy;
+export interface SocialTrackingConfig extends SocialTrackingScope {
+    access: SocialTrackingAccess;
+    connectionId?: string;
+    consumerKey: string;
+    credentialRefId?: string;
+    fallbackEnabled: boolean;
+    id: string;
+    idempotencyKey: string;
+    nextCollectionAt: string;
+    retention: SocialRetentionPolicy;
+    samplingIntervalMinutes: 30;
+    status: SocialTrackingStatus;
+    target: SocialTrackingTarget;
+}
+export interface SocialTrackingSyncState extends SocialTrackingScope {
+    cursor?: string;
+    lastFailureAt?: string;
+    lastSuccessAt?: string;
+    leaseExpiresAt?: string;
+    leaseOwner?: string;
+    trackingId: string;
+}
+export interface SocialTrackingFailure extends SocialTrackingScope {
+    at: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+    target: SocialTrackingTarget;
+    trackingId: string;
+}
+export interface SocialCollectionRunResult {
+    claimed: number;
+    completed: number;
+    failureEvidenceErrors: number;
+    failed: number;
+}
+export type SocialAnalyticsGranularity = 'thirty_minutes' | 'hour' | 'day' | 'week';
+export type SocialObservationQuality = 'complete' | 'partial' | 'source_gap';
+export interface SocialMetricSnapshot extends SocialTrackingScope {
+    consumerKey?: string;
+    evidence: SocialTrackingEvidence;
+    idempotencyKey: string;
+    metrics: readonly SocialMetricValue[];
+    observedAt: string;
+    quality: SocialObservationQuality;
+    target: SocialTrackingTarget;
+    unavailableMetrics?: readonly Pick<SocialMetricValue, 'key' | 'unit'>[];
+}
+export interface SocialMetricRollup extends SocialTrackingScope {
+    bucketEnd: string;
+    bucketStart: string;
+    consumerKey?: string;
+    delta?: number;
+    evidence: SocialTrackingEvidence;
+    first?: number;
+    granularity: Exclude<SocialAnalyticsGranularity, 'thirty_minutes'>;
+    key: SocialMetricKey;
+    latest?: number;
+    maximum?: number;
+    mean?: number;
+    minimum?: number;
+    quality: SocialObservationQuality;
+    sampleCount: number;
+    semantics: SocialMetricSemantics;
+    target: SocialTrackingTarget;
+    total?: number;
+    unit: SocialMetricUnit;
+}
+export interface SocialTrackingWebhookEvent extends SocialTrackingScope {
+    dedupeKey: string;
+    eventId: string;
+    eventType: string;
+    occurredAt: string;
+    platform: SocialPlatform;
+    target?: SocialTrackingTarget;
+}

package/dist/integrations/social/tracking-models.js

@@ -0,0 +1,2 @@
+// @bun
+var e={thirtyMinuteDays:90,hourlyDays:548,dailyDays:1826};export{e as DEFAULT_SOCIAL_RETENTION_POLICY};

package/dist/integrations/social/tracking-provider.d.ts

@@ -0,0 +1,53 @@
+import type { SocialPage, SocialPlatform } from './models.js';
+import type { SocialContent, SocialCreator, SocialMetricSnapshot, SocialTrackingAccess, SocialTrackingEvidence, SocialTrackingScope, SocialTrackingSelector, SocialTrackingSourceKind, SocialTrackingTarget, SocialTrackingWebhookEvent } from './tracking-models.js';
+export interface SocialTrackingContext extends SocialTrackingScope {
+    access: SocialTrackingAccess;
+    connectionId?: string;
+    correlationId: string;
+    credentialRefId?: string;
+    fallbackEnabled: boolean;
+    requestId: string;
+}
+export interface SocialTrackingSourceCapability {
+    available: boolean;
+    id: 'analytics.native' | 'content.list' | 'content.metrics' | 'creator.metrics' | 'history.native' | 'webhook';
+    reason?: string;
+}
+export interface SocialTrackingContentPage {
+    items: readonly SocialContent[];
+    page: SocialPage;
+}
+export interface SocialNativeBackfillInput {
+    from: string;
+    metricKeys?: readonly string[];
+    target: SocialTrackingTarget;
+    to: string;
+}
+export interface SocialTrackingSource {
+    readonly kind: SocialTrackingSourceKind;
+    readonly platform: SocialPlatform;
+    discoverCapabilities(context: SocialTrackingContext): Promise<readonly SocialTrackingSourceCapability[]>;
+    resolveCreator(context: SocialTrackingContext, selector: SocialTrackingSelector): Promise<SocialCreator>;
+    getCreator(context: SocialTrackingContext, creatorId: string): Promise<SocialCreator>;
+    listContent(context: SocialTrackingContext, input: {
+        creatorId: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<SocialTrackingContentPage>;
+    getContent(context: SocialTrackingContext, contentId: string): Promise<SocialContent>;
+    collectCreatorMetrics(context: SocialTrackingContext, creatorId: string): Promise<SocialMetricSnapshot>;
+    collectContentMetrics(context: SocialTrackingContext, contentId: string): Promise<SocialMetricSnapshot>;
+    backfillNative?(context: SocialTrackingContext, input: SocialNativeBackfillInput): Promise<readonly SocialMetricSnapshot[]>;
+    normalizeWebhook?(context: SocialTrackingContext, rawBody: Uint8Array, headers: Readonly<Record<string, string | undefined>>): Promise<SocialTrackingWebhookEvent | readonly SocialTrackingWebhookEvent[]>;
+}
+export interface SocialTrackingSourceSelection {
+    evidence: SocialTrackingEvidence;
+    rejections?: readonly {
+        reasons: readonly string[];
+        source: SocialTrackingSourceKind;
+    }[];
+    source: SocialTrackingSource;
+}
+export interface SocialTrackingSourceRegistry {
+    select(context: SocialTrackingContext, platform: SocialPlatform, requiredCapabilities?: readonly SocialTrackingSourceCapability['id'][]): Promise<SocialTrackingSourceSelection>;
+}

package/dist/integrations/social/tracking-provider.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/social/tracking-store.d.ts

@@ -0,0 +1,78 @@
+import type { SocialPlatform } from './models.js';
+import type { SocialAnalyticsGranularity, SocialCollectionRunResult, SocialContent, SocialCreator, SocialMetricKey, SocialMetricRollup, SocialMetricSnapshot, SocialRetentionPolicy, SocialTrackingConfig, SocialTrackingFailure, SocialTrackingScope, SocialTrackingSelector, SocialTrackingSyncState, SocialTrackingTarget, SocialTrackingWebhookEvent } from './tracking-models.js';
+import type { SocialTrackingContext } from './tracking-provider.js';
+export interface SocialAnalyticsQuery extends SocialTrackingScope {
+    consumerKey: string;
+    from: string;
+    granularity: SocialAnalyticsGranularity;
+    metricKeys: readonly SocialMetricKey[];
+    targets: readonly SocialTrackingTarget[];
+    to: string;
+}
+export interface SocialAnalyticsSeries {
+    key: SocialMetricKey;
+    points: readonly (SocialMetricSnapshot | SocialMetricRollup)[];
+    target: SocialTrackingTarget;
+}
+export interface SocialTrackingStore {
+    getCreator(scope: SocialTrackingScope, platform: SocialPlatform, id: string): Promise<SocialCreator | null>;
+    upsertCreator(scope: SocialTrackingScope, creator: SocialCreator): Promise<void>;
+    getContent(scope: SocialTrackingScope, platform: SocialPlatform, id: string): Promise<SocialContent | null>;
+    listCreatorContent(scope: SocialTrackingScope, platform: SocialPlatform, creatorId: string): Promise<readonly SocialContent[]>;
+    upsertContent(scope: SocialTrackingScope, content: SocialContent): Promise<void>;
+    getTracking(scope: SocialTrackingScope, trackingId: string): Promise<SocialTrackingConfig | null>;
+    listDueTracking(scope: SocialTrackingScope, dueAt: string, limit: number): Promise<readonly SocialTrackingConfig[]>;
+    listTrackingForTarget(scope: SocialTrackingScope, target: SocialTrackingTarget): Promise<readonly SocialTrackingConfig[]>;
+    claimDueTracking(scope: SocialTrackingScope, input: {
+        dueAt: string;
+        leaseOwner: string;
+        leaseUntil: string;
+        limit: number;
+    }): Promise<readonly SocialTrackingConfig[]>;
+    upsertTracking(config: SocialTrackingConfig): Promise<void>;
+    getSyncState(scope: SocialTrackingScope, trackingId: string): Promise<SocialTrackingSyncState | null>;
+    upsertSyncState(state: SocialTrackingSyncState): Promise<void>;
+    recordFailure(failure: SocialTrackingFailure): Promise<void>;
+    storeSnapshot(snapshot: SocialMetricSnapshot): Promise<'stored' | 'duplicate'>;
+    storeRollups(rollups: readonly SocialMetricRollup[]): Promise<void>;
+    queryAnalytics(query: SocialAnalyticsQuery): Promise<readonly SocialAnalyticsSeries[]>;
+    storeWebhookReceipt(event: SocialTrackingWebhookEvent): Promise<'stored' | 'duplicate'>;
+    applyRetention(scope: SocialTrackingScope, input: {
+        consumerKey: string;
+        now: string;
+        platform?: SocialPlatform;
+        policy: SocialRetentionPolicy;
+    }): Promise<void>;
+}
+export interface SocialTrackingService {
+    getCreator(scope: SocialTrackingScope, platform: SocialPlatform, id: string): Promise<SocialCreator | null>;
+    getContent(scope: SocialTrackingScope, platform: SocialPlatform, id: string): Promise<SocialContent | null>;
+    listCreatorContent(scope: SocialTrackingScope, platform: SocialPlatform, creatorId: string): Promise<readonly SocialContent[]>;
+    startCreatorTracking(input: {
+        context: SocialTrackingContext;
+        consumerKey: string;
+        idempotencyKey: string;
+        platform: SocialPlatform;
+        retention?: Partial<SocialRetentionPolicy>;
+        selector: SocialTrackingSelector;
+    }): Promise<SocialTrackingConfig>;
+    startContentTracking(input: {
+        context: SocialTrackingContext;
+        consumerKey: string;
+        contentId: string;
+        idempotencyKey: string;
+        platform: SocialPlatform;
+        retention?: Partial<SocialRetentionPolicy>;
+    }): Promise<SocialTrackingConfig>;
+    stopTracking(scope: SocialTrackingScope, trackingId: string): Promise<void>;
+    collectDue(scope: SocialTrackingScope, now: string, limit?: number): Promise<SocialCollectionRunResult>;
+    backfillNative(input: {
+        context: SocialTrackingContext;
+        from: string;
+        metricKeys?: readonly string[];
+        to: string;
+        trackingId: string;
+    }): Promise<number>;
+    queryAnalytics(query: SocialAnalyticsQuery): Promise<readonly SocialAnalyticsSeries[]>;
+    exportAnalyticsCsv(query: SocialAnalyticsQuery): Promise<string>;
+}

package/dist/integrations/social/tracking-store.js

@@ -0,0 +1 @@
+// @bun