@venturekit-pro/social 0.0.0-dev.20260602192622

package/dist/migrations/vk_social_0001_init.sql

@@ -0,0 +1,121 @@
+-- @venturekit-pro/social — initial schema.
+--
+-- Two tables:
+--
+--   social_platforms        — platform-admin-owned catalog of every
+--                             social network the package supports.
+--                             One row per (provider, adapter version).
+--                             The four v1 platforms are seeded by the
+--                             bottom of this migration.
+--
+--   tenant_social_platforms — per-tenant enable/disable + author-ref
+--                             pointer. NO cadence / fan-out / locale
+--                             fields here — those are calling-app
+--                             concerns. Apps that want per-platform
+--                             cadence settings model that in their
+--                             own schema.
+--
+-- Append-only fields are not used here; the rows are tenant-mutable
+-- (toggle enabled, swap author_ref). Audit-worthy changes flow into
+-- `@venturekit-pro/audit`'s `audit_events` separately.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── social_platforms (catalog) ─────────────────────────────────────
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'vk_social_platform_status') THEN
+    CREATE TYPE vk_social_platform_status AS ENUM (
+      'available',
+      'deprecated',
+      'disabled'
+    );
+  END IF;
+END
+$$;
+
+CREATE TABLE IF NOT EXISTS social_platforms (
+  key            varchar(64)               PRIMARY KEY,
+  display_name   varchar(255)              NOT NULL,
+  -- Lifecycle: `available` rows render in pickers; `deprecated` ones
+  -- are still callable but the UI nudges a swap; `disabled` rows
+  -- refuse to publish at the adapter resolution boundary.
+  status         vk_social_platform_status NOT NULL DEFAULT 'available',
+  -- Human-readable description for picker rows.
+  description    text,
+  -- Free-form metadata (icon name, brand color, etc). Apps consume
+  -- this for UI rendering without the package needing to enumerate
+  -- every visual property.
+  meta           jsonb                     NOT NULL DEFAULT '{}'::jsonb,
+  -- When the row was first introduced + lifecycle timestamps. Used
+  -- by the platform-admin UI to render badges.
+  introduced_at  timestamptz               NOT NULL DEFAULT now(),
+  deprecated_at  timestamptz,
+  disabled_at    timestamptz,
+  created_at     timestamptz               NOT NULL DEFAULT now(),
+  updated_at     timestamptz               NOT NULL DEFAULT now()
+);
+
+-- ─── tenant_social_platforms (per-tenant) ───────────────────────────
+--
+-- Apps that want per-platform-per-tenant settings (cadence, locales,
+-- fan-out weeks) extend THIS table in their own migration. We keep
+-- the package-owned columns to the strict minimum: enabled flag,
+-- author ref (the platform-side id we publish into), and optional
+-- vendor metadata.
+
+CREATE TABLE IF NOT EXISTS tenant_social_platforms (
+  tenant_id        uuid                     NOT NULL,
+  platform_key     varchar(64)              NOT NULL REFERENCES social_platforms(key) ON DELETE RESTRICT,
+  enabled          boolean                  NOT NULL DEFAULT TRUE,
+  -- Platform-side identifier this tenant publishes to. URN / page id /
+  -- ig user id. Required when enabled = TRUE; the application enforces
+  -- that invariant at the service boundary (we don't put a CHECK here
+  -- because the empty string is sometimes used as a placeholder
+  -- during onboarding wizards).
+  author_ref       varchar(512)             NOT NULL DEFAULT '',
+  -- Free-form metadata stamped by the tenant ops flow (locale,
+  -- scopes, etc). Adapters ignore unless documented.
+  meta             jsonb                    NOT NULL DEFAULT '{}'::jsonb,
+  created_at       timestamptz              NOT NULL DEFAULT now(),
+  updated_at       timestamptz              NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, platform_key)
+);
+
+CREATE INDEX IF NOT EXISTS tenant_social_platforms_enabled_idx
+  ON tenant_social_platforms (tenant_id)
+  WHERE enabled;
+
+-- ─── Catalog seed ───────────────────────────────────────────────────
+--
+-- Idempotent (ON CONFLICT DO NOTHING) so re-running the migration on
+-- an already-seeded DB is a no-op. Tenants who want to add custom
+-- adapters (e.g. Mastodon, Bluesky) insert their own row at app boot.
+
+INSERT INTO social_platforms (key, display_name, description, meta) VALUES
+  (
+    'linkedin',
+    'LinkedIn',
+    'Professional network. UGC Posts API (v2). Author URN required.',
+    jsonb_build_object('iconKey', 'linkedin', 'brandColor', '#0A66C2')
+  ),
+  (
+    'x',
+    'X',
+    'Microblogging (formerly Twitter). v2 Tweets API. 280-char body.',
+    jsonb_build_object('iconKey', 'x', 'brandColor', '#000000')
+  ),
+  (
+    'facebook',
+    'Facebook',
+    'Meta Graph API for Pages. Page access token required.',
+    jsonb_build_object('iconKey', 'facebook', 'brandColor', '#1877F2')
+  ),
+  (
+    'instagram',
+    'Instagram',
+    'Meta Graph Content Publishing API (Business / Creator accounts).',
+    jsonb_build_object('iconKey', 'instagram', 'brandColor', '#E4405F')
+  )
+ON CONFLICT (key) DO NOTHING;

package/dist/path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Migrations-dir helper — same shape as `@venturekit-pro/audit`.
+ *
+ * Wired into `vk.config.ts:extraMigrationsDirs` so `vk migrate` picks
+ * up the package's `vk_social_*.sql` files alongside the project's
+ * own migrations.
+ */
+export declare function getSocialMigrationsDir(): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,wBAAgB,sBAAsB,IAAI,MAAM,CAM/C"}

package/dist/path.js

@@ -0,0 +1,17 @@
+/**
+ * Migrations-dir helper — same shape as `@venturekit-pro/audit`.
+ *
+ * Wired into `vk.config.ts:extraMigrationsDirs` so `vk migrate` picks
+ * up the package's `vk_social_*.sql` files alongside the project's
+ * own migrations.
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function getSocialMigrationsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // After build: dist/path.js, migrations under dist/migrations/.
+    // From source (workspace symlink): src/path.ts, migrations under
+    // src/migrations/. Both resolve to the same relative subdir.
+    return path.join(here, 'migrations');
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,iEAAiE;IACjE,6DAA6D;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Adapter registry — a small lookup table consumers populate once at
+ * boot time with the adapters they want to enable.
+ *
+ *   const registry = createAdapterRegistry([
+ *     linkedinAdapter,
+ *     xAdapter,
+ *     facebookAdapter,
+ *     instagramAdapter,
+ *   ]);
+ *
+ *   const adapter = registry.resolve('linkedin');
+ *   const result  = await adapter.publish(post, credentials);
+ *
+ * The registry is a thin Map — no resolution policy beyond exact
+ * key match. Apps that need fallback (e.g. "instagram" → "meta") can
+ * compose a wrapper.
+ */
+import type { SocialAdapter } from './adapter.js';
+import type { SocialPlatformKey } from './types.js';
+export interface AdapterRegistry {
+    /** All registered adapters in registration order. */
+    list(): SocialAdapter[];
+    /** Look up by key; `undefined` if not registered. */
+    find(key: SocialPlatformKey): SocialAdapter | undefined;
+    /** Look up by key or throw — for hot paths where the row MUST exist. */
+    resolve(key: SocialPlatformKey): SocialAdapter;
+    /** Set of supported keys. */
+    keys(): SocialPlatformKey[];
+}
+export declare function createAdapterRegistry(adapters: SocialAdapter[]): AdapterRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,IAAI,IAAI,aAAa,EAAE,CAAC;IACxB,qDAAqD;IACrD,IAAI,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAAC;IACxD,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa,CAAC;IAC/C,6BAA6B;IAC7B,IAAI,IAAI,iBAAiB,EAAE,CAAC;CAC7B;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,eAAe,CAwBhF"}

package/dist/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Adapter registry — a small lookup table consumers populate once at
+ * boot time with the adapters they want to enable.
+ *
+ *   const registry = createAdapterRegistry([
+ *     linkedinAdapter,
+ *     xAdapter,
+ *     facebookAdapter,
+ *     instagramAdapter,
+ *   ]);
+ *
+ *   const adapter = registry.resolve('linkedin');
+ *   const result  = await adapter.publish(post, credentials);
+ *
+ * The registry is a thin Map — no resolution policy beyond exact
+ * key match. Apps that need fallback (e.g. "instagram" → "meta") can
+ * compose a wrapper.
+ */
+export function createAdapterRegistry(adapters) {
+    const byKey = new Map();
+    for (const a of adapters) {
+        if (byKey.has(a.key)) {
+            throw new Error(`[social/registry] Duplicate adapter key: '${a.key}'`);
+        }
+        byKey.set(a.key, a);
+    }
+    const all = adapters.slice();
+    return {
+        list: () => all.slice(),
+        find: (key) => byKey.get(key),
+        resolve(key) {
+            const a = byKey.get(key);
+            if (!a) {
+                throw new Error(`[social/registry] No adapter registered for key '${key}'. ` +
+                    `Registered: [${Array.from(byKey.keys()).join(', ')}]`);
+            }
+            return a;
+        },
+        keys: () => Array.from(byKey.keys()),
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH,MAAM,UAAU,qBAAqB,CAAC,QAAyB;IAC7D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC7B,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;QACvB,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;QAC7B,OAAO,CAAC,GAAG;YACT,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,CAAC,CAAC,EAAE,CAAC;gBACP,MAAM,IAAI,KAAK,CACb,oDAAoD,GAAG,KAAK;oBAC1D,gBAAgB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzD,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;KACrC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Generic social-publishing types.
+ *
+ * Intentionally domain-neutral: this package knows about platforms,
+ * posts, media, OAuth credentials, and publish results. It does not
+ * know about cadence, fan-out, angles, AI generation, or any other
+ * concept a calling app might build on top.
+ *
+ * The catalog of supported platforms is a database row (`social_platforms`,
+ * shipped by `migrations/vk_social_0001_init.sql`); the package
+ * provides an adapter implementation per row.
+ */
+/**
+ * Platform identifier — stable string keyed against the
+ * `social_platforms.key` column. Adding a new platform requires:
+ *   1. A row in `social_platforms`.
+ *   2. An adapter under `adapters/<key>.ts`.
+ *   3. A registration in the consumer's `createAdapterRegistry()` call.
+ *
+ * The four v1 platforms ship in this package. Apps with their own
+ * adapter (e.g. Mastodon, Bluesky) register them at runtime.
+ */
+export type SocialPlatformKey = 'linkedin' | 'x' | 'facebook' | 'instagram' | string;
+/**
+ * OAuth credentials a tenant supplies for a given platform. The
+ * package never reads or writes these; the caller fetches them from
+ * its own secret store (KMS-encrypted DB jsonb in the CMS) and
+ * passes them per call.
+ *
+ * `accessToken` is the bearer token used on every API call.
+ * Refresh-token logic lives in `oauth.ts` for platforms that
+ * support it; expired-token detection surfaces as a typed error so
+ * the caller can re-fetch from its secret store.
+ */
+export interface OAuthCredentials {
+    /** Platform-issued access token (bearer-style). */
+    accessToken: string;
+    /** Optional refresh token; passed to `refreshTokens()` when present. */
+    refreshToken?: string;
+    /**
+     * Optional ISO timestamp when the access token expires. When
+     * present, adapters MAY refuse to call upstream if the timestamp
+     * is in the past + ask the caller to refresh.
+     */
+    expiresAt?: string;
+    /**
+     * Platform-specific identifier for *what* to publish to. Examples:
+     *   - LinkedIn: `'urn:li:organization:12345'` (the org's URN)
+     *   - X:        the user/page handle
+     *   - Facebook: `'page_<pageId>'`
+     *   - Instagram: `'ig_user_<igUserId>'`
+     *
+     * Stored alongside the access token so a single tenant can have
+     * different (token, target) pairs per platform.
+     */
+    authorRef: string;
+    /**
+     * Free-form vendor metadata stamped onto the credential pair (e.g.
+     * scopes, locale). Optional; adapters ignore it unless documented
+     * to read it.
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * One piece of media attached to a post.
+ *
+ * `url` must be publicly fetchable by the platform's upload API.
+ * Pre-signed URLs are fine; private S3 keys are not.
+ */
+export interface SocialMedia {
+    url: string;
+    /** MIME type — used by the upload step to short-circuit on unsupported types. */
+    mimeType: string;
+    /** Bytes; helps the adapter pick chunked-upload vs single-shot. */
+    sizeBytes?: number;
+    /** Optional alt text — passed through where supported. */
+    altText?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * A platform-neutral social post. Adapters convert this to the
+ * vendor's expected request shape inside `publish()`.
+ */
+export interface SocialPost {
+    /** Free-text body. Length / hashtag rules enforced by `validate()`. */
+    body: string;
+    /** Attached media (images / videos). */
+    media?: SocialMedia[];
+    /** Optional canonical link forwarded to platforms with link-preview unfurling. */
+    link?: string;
+    /** First-comment companion thread (LinkedIn, X). Ignored on platforms that don't support it. */
+    firstComment?: string;
+    /**
+     * Idempotency token forwarded to vendor APIs that support it (LinkedIn,
+     * Meta Graph). Used to make retries safe.
+     */
+    idempotencyKey?: string;
+    /** Caller-side correlation id (audit + log fan-out). */
+    correlationId?: string;
+}
+/** Reasons `validate()` may surface. */
+export type SocialValidationCode = 'body_empty' | 'body_too_long' | 'body_too_short' | 'hashtag_count_low' | 'hashtag_count_high' | 'media_required' | 'media_count_high' | 'aspect_ratio_unsupported' | 'media_too_large' | 'media_mime_unsupported' | 'link_invalid';
+export interface SocialValidationIssue {
+    code: SocialValidationCode;
+    message: string;
+    /** Severity — `error` blocks publish; `warning` is informational. */
+    severity: 'error' | 'warning';
+}
+export interface SocialValidationResult {
+    ok: boolean;
+    issues: SocialValidationIssue[];
+}
+/** Constraints used by `validate()`. Adapters override at construction. */
+export interface SocialPlatformConstraints {
+    maxBodyChars: number;
+    /** Set to 0 to disable the body-required check. */
+    minBodyChars: number;
+    minHashtags: number;
+    maxHashtags: number;
+    /** Required media types (or `[]` to allow text-only). */
+    allowedMimeTypes: string[];
+    /** Max attachments per post; 0 = no media allowed; -1 = no cap. */
+    maxMediaCount: number;
+    /** Allowed aspect-ratio strings (`'1:1' | '4:5' | '16:9' | …`). */
+    allowedAspectRatios: string[];
+    /** Cap per attachment in bytes. -1 = no cap. */
+    maxMediaSizeBytes: number;
+    /** Whether `first_comment` is supported. */
+    supportsFirstComment: boolean;
+    /**
+     * Whether the platform refuses text-only posts (Instagram is the
+     * canonical case). Defaults to `false` — most platforms accept a
+     * naked body. Set independently of `minBodyChars`: Instagram requires
+     * BOTH a non-empty caption AND at least one media item, so the
+     * heuristic "media required when minBodyChars === 0" doesn't fit.
+     */
+    requiresMedia?: boolean;
+}
+/**
+ * Result of a successful publish. Adapters fill in everything they
+ * can; minimum contract is `externalRef`.
+ */
+export interface PublishResult {
+    /** Platform-native id (URN / tweet id / post id / media id). */
+    externalRef: string;
+    /** Public URL when known. Some platforms don't expose this immediately. */
+    publishedUrl?: string;
+    /** ISO timestamp when the platform accepted the post. */
+    publishedAt: string;
+    /** Echo of the caller's idempotency token. */
+    idempotencyKey?: string;
+    /** Echo of the caller's correlation id. */
+    correlationId?: string;
+    /** Raw vendor response — opaque, surfaced for debugging only. */
+    raw?: unknown;
+}
+/**
+ * Status check result. Useful when a publish was accepted async and
+ * the caller wants to know whether it actually landed.
+ */
+export interface VerifyResult {
+    status: 'pending' | 'published' | 'failed' | 'deleted' | 'unknown';
+    publishedUrl?: string;
+    /** Platform-side error message when `status === 'failed'`. */
+    errorMessage?: string;
+    raw?: unknown;
+}
+/**
+ * Webhook payload classifier output. Used by callers that wire a
+ * platform's webhooks into their own job queue.
+ */
+export interface WebhookEvent {
+    /** Which platform fired the event. */
+    platform: SocialPlatformKey;
+    /** Native event type ('post.created', 'post.deleted', etc). Free-form. */
+    kind: string;
+    /** Foreign key matching `PublishResult.externalRef`. */
+    externalRef: string;
+    /** Best-effort timestamp; falls back to `now()` if the vendor omits one. */
+    occurredAt: string;
+    /** Raw payload echoed back for downstream logging. */
+    raw: unknown;
+}
+/**
+ * Base class for typed publish errors. Adapters throw subclasses;
+ * callers `instanceof` to differentiate retry-worthy from permanent
+ * failures.
+ */
+export declare class SocialPublishError extends Error {
+    readonly platform: SocialPlatformKey;
+    /** HTTP status code from the upstream call, when applicable. */
+    readonly status?: number;
+    /** Raw vendor response body (truncated to 1KB). */
+    readonly raw?: unknown;
+    constructor(message: string, opts: {
+        platform: SocialPlatformKey;
+        status?: number;
+        raw?: unknown;
+    });
+}
+/** Bad / expired credentials. Caller should re-fetch + retry. */
+export declare class SocialAuthError extends SocialPublishError {
+    constructor(message: string, opts: {
+        platform: SocialPlatformKey;
+        status?: number;
+        raw?: unknown;
+    });
+}
+/** Rate limit hit — caller should back off and retry. */
+export declare class SocialRateLimitError extends SocialPublishError {
+    /** Suggested retry-after seconds, from upstream headers when present. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, opts: {
+        platform: SocialPlatformKey;
+        status?: number;
+        raw?: unknown;
+        retryAfterSeconds?: number;
+    });
+}
+/** Validation rejection from the platform (caught body, malformed media). */
+export declare class SocialValidationError extends SocialPublishError {
+    constructor(message: string, opts: {
+        platform: SocialPlatformKey;
+        status?: number;
+        raw?: unknown;
+    });
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,GAAG,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAErF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,0BAA0B,GAC1B,iBAAiB,GACjB,wBAAwB,GACxB,cAAc,CAAC;AAEnB,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,GAAG,EAAE,OAAO,CAAC;CACd;AAID;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QACjC,QAAQ,EAAE,iBAAiB,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,OAAO,CAAC;KACf;CAOF;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,kBAAkB;gBACzC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE;CAInG;AAED,yDAAyD;AACzD,qBAAa,oBAAqB,SAAQ,kBAAkB;IAC1D,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAElC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE;CAMpG;AAED,6EAA6E;AAC7E,qBAAa,qBAAsB,SAAQ,kBAAkB;gBAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE;CAInG"}

package/dist/types.js

@@ -0,0 +1,57 @@
+/**
+ * Generic social-publishing types.
+ *
+ * Intentionally domain-neutral: this package knows about platforms,
+ * posts, media, OAuth credentials, and publish results. It does not
+ * know about cadence, fan-out, angles, AI generation, or any other
+ * concept a calling app might build on top.
+ *
+ * The catalog of supported platforms is a database row (`social_platforms`,
+ * shipped by `migrations/vk_social_0001_init.sql`); the package
+ * provides an adapter implementation per row.
+ */
+// ─── Typed errors ──────────────────────────────────────────────────────
+/**
+ * Base class for typed publish errors. Adapters throw subclasses;
+ * callers `instanceof` to differentiate retry-worthy from permanent
+ * failures.
+ */
+export class SocialPublishError extends Error {
+    platform;
+    /** HTTP status code from the upstream call, when applicable. */
+    status;
+    /** Raw vendor response body (truncated to 1KB). */
+    raw;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'SocialPublishError';
+        this.platform = opts.platform;
+        this.status = opts.status;
+        this.raw = opts.raw;
+    }
+}
+/** Bad / expired credentials. Caller should re-fetch + retry. */
+export class SocialAuthError extends SocialPublishError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = 'SocialAuthError';
+    }
+}
+/** Rate limit hit — caller should back off and retry. */
+export class SocialRateLimitError extends SocialPublishError {
+    /** Suggested retry-after seconds, from upstream headers when present. */
+    retryAfterSeconds;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = 'SocialRateLimitError';
+        this.retryAfterSeconds = opts.retryAfterSeconds;
+    }
+}
+/** Validation rejection from the platform (caught body, malformed media). */
+export class SocialValidationError extends SocialPublishError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = 'SocialValidationError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoMH,0EAA0E;AAE1E;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,QAAQ,CAAoB;IACrC,gEAAgE;IACvD,MAAM,CAAU;IACzB,mDAAmD;IAC1C,GAAG,CAAW;IACvB,YAAY,OAAe,EAAE,IAI5B;QACC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACtB,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,eAAgB,SAAQ,kBAAkB;IACrD,YAAY,OAAe,EAAE,IAAqE;QAChG,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,oBAAqB,SAAQ,kBAAkB;IAC1D,yEAAyE;IAChE,iBAAiB,CAAU;IACpC,YACE,OAAe,EACf,IAAiG;QAEjG,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;IAClD,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,qBAAsB,SAAQ,kBAAkB;IAC3D,YAAY,OAAe,EAAE,IAAqE;QAChG,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/validation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generic post-validation. Adapters compose this with their per-
+ * platform `SocialPlatformConstraints` to surface a uniform error
+ * shape without re-implementing every check four times.
+ *
+ * Returns BOTH errors AND warnings. Callers MUST block publish on
+ * `severity === 'error'`; warnings are informational ("you only
+ * have 1 hashtag, LinkedIn recommends 2-5").
+ */
+import type { SocialPlatformConstraints, SocialPost, SocialValidationResult } from './types.js';
+export declare function validatePost(post: SocialPost, constraints: SocialPlatformConstraints): SocialValidationResult;
+/**
+ * Reduce `(width, height)` to a normalized `W:H` ratio string.
+ * Matches the format used in `allowedAspectRatios`.
+ */
+export declare function simplifyRatio(width: number, height: number): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,yBAAyB,EACzB,UAAU,EAEV,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAKpB,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,yBAAyB,GACrC,sBAAsB,CA+HxB;AAgBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAInE"}