@framers/agentos 0.1.52 → 0.1.53

package/dist/social-posting/SocialAbstractService.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Shared HTTP primitives for social channel services.
+ * @module @framers/agentos/social-posting/SocialAbstractService
+ */
+export interface SocialRequestOptions {
+    /** Retry attempts after the initial request. */
+    maxRetries?: number;
+    /** Base delay for exponential backoff (ms). */
+    retryDelayMs?: number;
+    /** Max delay cap for backoff (ms). */
+    maxRetryDelayMs?: number;
+    /** Request timeout (ms). */
+    timeoutMs?: number;
+    /** Optional override for retryable HTTP status logic. */
+    shouldRetryStatus?: (status: number) => boolean;
+}
+export interface SocialServiceConfig {
+    /** Minimum spacing between outbound API requests. */
+    minRequestIntervalMs?: number;
+    /** Default retry attempts after initial request. */
+    defaultMaxRetries?: number;
+    /** Default base retry delay (ms). */
+    defaultRetryDelayMs?: number;
+    /** Default request timeout (ms). */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Base class for social channel service layers.
+ *
+ * Adds:
+ * - request rate-limiting
+ * - retry with exponential backoff on retryable failures
+ * - JSON request/response helpers
+ * - OAuth scope assertion helper
+ */
+export declare abstract class SocialAbstractService {
+    private readonly minRequestIntervalMs;
+    private readonly defaultMaxRetries;
+    private readonly defaultRetryDelayMs;
+    private readonly defaultTimeoutMs;
+    private lastRequestAt;
+    private rateLimiter;
+    protected constructor(config?: SocialServiceConfig);
+    protected fetchJson<T>(url: string, init?: RequestInit, options?: SocialRequestOptions): Promise<T>;
+    protected fetchText(url: string, init?: RequestInit, options?: SocialRequestOptions): Promise<string>;
+    protected fetchWithRetry(url: string, init?: RequestInit, options?: SocialRequestOptions): Promise<Response>;
+    protected assertScopes(requiredScopes: string[], grantedScopes?: string[]): void;
+    private fetchOnce;
+    private waitForRateLimit;
+    private computeBackoff;
+}
+//# sourceMappingURL=SocialAbstractService.d.ts.map

package/dist/social-posting/SocialAbstractService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialAbstractService.d.ts","sourceRoot":"","sources":["../../src/social-posting/SocialAbstractService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAYD;;;;;;;;GAQG;AACH,8BAAsB,qBAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,WAAW,CAAoC;IAEvD,SAAS,aAAa,MAAM,GAAE,mBAAwB;cAOtC,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC;cAWG,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC;cAKF,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,QAAQ,CAAC;IAoCpB,SAAS,CAAC,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,MAAM,EAAO,GAAG,IAAI;YAQtE,SAAS;YAgCT,gBAAgB;IAkB9B,OAAO,CAAC,cAAc;CAIvB"}

package/dist/social-posting/SocialAbstractService.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Shared HTTP primitives for social channel services.
+ * @module @framers/agentos/social-posting/SocialAbstractService
+ */
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 300;
+const DEFAULT_MAX_RETRY_DELAY_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 15000;
+const defaultRetryStatus = (status) => status === 429 || status >= 500;
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Base class for social channel service layers.
+ *
+ * Adds:
+ * - request rate-limiting
+ * - retry with exponential backoff on retryable failures
+ * - JSON request/response helpers
+ * - OAuth scope assertion helper
+ */
+export class SocialAbstractService {
+    constructor(config = {}) {
+        this.lastRequestAt = 0;
+        this.rateLimiter = Promise.resolve();
+        this.minRequestIntervalMs = Math.max(0, config.minRequestIntervalMs ?? 0);
+        this.defaultMaxRetries = Math.max(0, config.defaultMaxRetries ?? DEFAULT_MAX_RETRIES);
+        this.defaultRetryDelayMs = Math.max(1, config.defaultRetryDelayMs ?? DEFAULT_RETRY_DELAY_MS);
+        this.defaultTimeoutMs = Math.max(1, config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+    }
+    async fetchJson(url, init = {}, options = {}) {
+        const res = await this.fetchWithRetry(url, init, options);
+        const contentType = (res.headers.get('content-type') ?? '').toLowerCase();
+        if (contentType.includes('application/json')) {
+            return (await res.json());
+        }
+        const text = await res.text();
+        return text;
+    }
+    async fetchText(url, init = {}, options = {}) {
+        const res = await this.fetchWithRetry(url, init, options);
+        return res.text();
+    }
+    async fetchWithRetry(url, init = {}, options = {}) {
+        const maxRetries = options.maxRetries ?? this.defaultMaxRetries;
+        const retryDelayMs = options.retryDelayMs ?? this.defaultRetryDelayMs;
+        const maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+        const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs;
+        const shouldRetryStatus = options.shouldRetryStatus ?? defaultRetryStatus;
+        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+            let response = null;
+            try {
+                await this.waitForRateLimit();
+                response = await this.fetchOnce(url, init, timeoutMs);
+            }
+            catch (err) {
+                if (attempt >= maxRetries) {
+                    throw err instanceof Error ? err : new Error(String(err));
+                }
+                await wait(this.computeBackoff(attempt, retryDelayMs, maxRetryDelayMs));
+                continue;
+            }
+            if (response.ok)
+                return response;
+            if (attempt < maxRetries && shouldRetryStatus(response.status)) {
+                await wait(this.computeBackoff(attempt, retryDelayMs, maxRetryDelayMs));
+                continue;
+            }
+            const body = await response.text().catch(() => '');
+            throw new Error(`HTTP ${response.status} ${response.statusText}${body ? `: ${body}` : ''}`);
+        }
+        throw new Error('Request failed after retry attempts were exhausted.');
+    }
+    assertScopes(requiredScopes, grantedScopes = []) {
+        const granted = new Set(grantedScopes);
+        const missing = requiredScopes.filter((scope) => !granted.has(scope));
+        if (missing.length === 0)
+            return;
+        throw new Error(`Missing required OAuth scopes: ${missing.join(', ')}`);
+    }
+    async fetchOnce(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const normalizedInit = {
+                ...init,
+                signal: controller.signal,
+            };
+            if (normalizedInit.body &&
+                typeof normalizedInit.body === 'object' &&
+                !(normalizedInit.body instanceof URLSearchParams) &&
+                !(normalizedInit.body instanceof FormData) &&
+                !(normalizedInit.body instanceof Blob) &&
+                !(normalizedInit.body instanceof ArrayBuffer)) {
+                normalizedInit.body = JSON.stringify(normalizedInit.body);
+                const headers = new Headers(normalizedInit.headers ?? {});
+                if (!headers.has('content-type')) {
+                    headers.set('content-type', 'application/json');
+                }
+                normalizedInit.headers = headers;
+            }
+            return await fetch(url, normalizedInit);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async waitForRateLimit() {
+        this.rateLimiter = this.rateLimiter.then(async () => {
+            if (this.minRequestIntervalMs <= 0) {
+                this.lastRequestAt = Date.now();
+                return;
+            }
+            const now = Date.now();
+            const delta = now - this.lastRequestAt;
+            const waitMs = Math.max(0, this.minRequestIntervalMs - delta);
+            if (waitMs > 0) {
+                await wait(waitMs);
+            }
+            this.lastRequestAt = Date.now();
+        });
+        return this.rateLimiter;
+    }
+    computeBackoff(attempt, baseMs, capMs) {
+        const raw = baseMs * 2 ** attempt;
+        return Math.min(capMs, raw);
+    }
+}
+//# sourceMappingURL=SocialAbstractService.js.map

package/dist/social-posting/SocialAbstractService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialAbstractService.js","sourceRoot":"","sources":["../../src/social-posting/SocialAbstractService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AACxC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC,MAAM,kBAAkB,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;AAExF,MAAM,IAAI,GAAG,CAAC,EAAU,EAAiB,EAAE,CACzC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,OAAgB,qBAAqB;IAQzC,YAAsB,SAA8B,EAAE;QAH9C,kBAAa,GAAG,CAAC,CAAC;QAClB,gBAAW,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;QAGrD,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC,CAAC;QAC1E,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,iBAAiB,IAAI,mBAAmB,CAAC,CAAC;QACtF,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,mBAAmB,IAAI,sBAAsB,CAAC,CAAC;QAC7F,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,CAAC;IACrF,CAAC;IAES,KAAK,CAAC,SAAS,CACvB,GAAW,EACX,OAAoB,EAAE,EACtB,UAAgC,EAAE;QAElC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1D,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1E,IAAI,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;QACjC,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,IAAoB,CAAC;IAC9B,CAAC;IAES,KAAK,CAAC,SAAS,CACvB,GAAW,EACX,OAAoB,EAAE,EACtB,UAAgC,EAAE;QAElC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAES,KAAK,CAAC,cAAc,CAC5B,GAAW,EACX,OAAoB,EAAE,EACtB,UAAgC,EAAE;QAElC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,iBAAiB,CAAC;QAChE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,mBAAmB,CAAC;QACtE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,0BAA0B,CAAC;QAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAC7D,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,kBAAkB,CAAC;QAE1E,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;YAC1D,IAAI,QAAQ,GAAoB,IAAI,CAAC;YACrC,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC9B,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YACxD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;oBAC1B,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC5D,CAAC;gBACD,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC;gBACxE,SAAS;YACX,CAAC;YAED,IAAI,QAAQ,CAAC,EAAE;gBAAE,OAAO,QAAQ,CAAC;YAEjC,IAAI,OAAO,GAAG,UAAU,IAAI,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC/D,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC;gBACxE,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,QAAQ,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3E,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAES,YAAY,CAAC,cAAwB,EAAE,gBAA0B,EAAE;QAC3E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEjC,MAAM,IAAI,KAAK,CAAC,kCAAkC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,IAAiB,EAAE,SAAiB;QACvE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAEhE,IAAI,CAAC;YACH,MAAM,cAAc,GAAgB;gBAClC,GAAG,IAAI;gBACP,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;YAEF,IACE,cAAc,CAAC,IAAI;gBACnB,OAAO,cAAc,CAAC,IAAI,KAAK,QAAQ;gBACvC,CAAC,CAAC,cAAc,CAAC,IAAI,YAAY,eAAe,CAAC;gBACjD,CAAC,CAAC,cAAc,CAAC,IAAI,YAAY,QAAQ,CAAC;gBAC1C,CAAC,CAAC,cAAc,CAAC,IAAI,YAAY,IAAI,CAAC;gBACtC,CAAC,CAAC,cAAc,CAAC,IAAI,YAAY,WAAW,CAAC,EAC7C,CAAC;gBACD,cAAc,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;gBAC1D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;gBAC1D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;oBACjC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;gBAClD,CAAC;gBACD,cAAc,CAAC,OAAO,GAAG,OAAO,CAAC;YACnC,CAAC;YAED,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC1C,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,gBAAgB;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAClD,IAAI,IAAI,CAAC,oBAAoB,IAAI,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAChC,OAAO;YACT,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,oBAAoB,GAAG,KAAK,CAAC,CAAC;YAC9D,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACf,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,CAAC;YACD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,cAAc,CAAC,OAAe,EAAE,MAAc,EAAE,KAAa;QACnE,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC;QAClC,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/social-posting/SocialPostManager.d.ts

@@ -0,0 +1,252 @@
+/**
+ * @fileoverview Social Post Manager — post lifecycle engine.
+ * @module @framers/agentos/social-posting/SocialPostManager
+ *
+ * Manages the full lifecycle of social media posts through a state machine:
+ *
+ *   DRAFT --> SCHEDULED --> PUBLISHING --> PUBLISHED
+ *                              |
+ *                            ERROR --> RETRY --> PUBLISHING
+ *
+ * Storage is in-memory (Map<string, SocialPost>). The backend module will
+ * layer on DB persistence via IStorageAdapter when this is wired into
+ * the NestJS service layer.
+ *
+ * @example
+ * ```typescript
+ * import { SocialPostManager } from '../social-posting';
+ *
+ * const manager = new SocialPostManager();
+ *
+ * const post = manager.createDraft({
+ *   seedId: 'agent-alpha',
+ *   content: 'Hello world!',
+ *   platforms: ['twitter', 'bluesky'],
+ * });
+ *
+ * manager.schedulePost(post.id, '2026-03-05T12:00:00Z');
+ * ```
+ */
+/**
+ * State machine states for a social post.
+ *
+ * Valid transitions:
+ * - draft      --> scheduled | publishing
+ * - scheduled  --> publishing
+ * - publishing --> published | error
+ * - error      --> retry
+ * - retry      --> publishing
+ */
+export type SocialPostStatus = 'draft' | 'scheduled' | 'publishing' | 'published' | 'error' | 'retry';
+/**
+ * Per-platform publishing result tracked on a SocialPost.
+ */
+export interface SocialPostPlatformResult {
+    /** Target platform identifier (e.g. 'twitter', 'bluesky'). */
+    platform: string;
+    /** Platform-assigned post ID after successful publish. */
+    postId?: string;
+    /** Canonical URL of the published post. */
+    url?: string;
+    /** Current status for this platform leg. */
+    status: 'pending' | 'success' | 'error';
+    /** Error message if status is 'error'. */
+    error?: string;
+    /** ISO 8601 timestamp of successful publish. */
+    publishedAt?: string;
+}
+/**
+ * A social post managed by the SocialPostManager.
+ *
+ * `adaptations` maps platform names to platform-specific content variants
+ * produced by the ContentAdaptationEngine (or by the LLM skill layer).
+ */
+export interface SocialPost {
+    /** Unique post identifier (UUID v4). */
+    id: string;
+    /** The agent seed this post belongs to. */
+    seedId: string;
+    /** The original, platform-agnostic content. */
+    baseContent: string;
+    /** Platform-specific content adaptations (platform --> adapted text). */
+    adaptations: Record<string, string>;
+    /** Target platforms for this post. */
+    platforms: string[];
+    /** Optional media attachment URLs. */
+    mediaUrls?: string[];
+    /** ISO 8601 timestamp when the post should be published. */
+    scheduledAt?: string;
+    /** Current lifecycle status. */
+    status: SocialPostStatus;
+    /** Per-platform publishing results. */
+    results: Record<string, SocialPostPlatformResult>;
+    /** Number of retry attempts so far. */
+    retryCount: number;
+    /** Maximum retry attempts before permanent failure. */
+    maxRetries: number;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-update timestamp. */
+    updatedAt: string;
+}
+/**
+ * Input for creating a new draft post.
+ */
+export interface CreateDraftInput {
+    /** The agent seed this post belongs to. */
+    seedId: string;
+    /** The base content for the post. */
+    content: string;
+    /** Target platforms (e.g. ['twitter', 'linkedin']). */
+    platforms: string[];
+    /** Optional media attachment URLs. */
+    mediaUrls?: string[];
+    /** Pre-computed platform adaptations (platform --> adapted text). */
+    adaptations?: Record<string, string>;
+    /** ISO 8601 scheduled publish time. If omitted, the post stays as a draft. */
+    schedule?: string;
+}
+/**
+ * Manages the lifecycle of social media posts.
+ *
+ * Provides create, schedule, publish, retry, and query operations over an
+ * in-memory store. Platform-specific publishing is delegated to callers
+ * (typically the ToolExecutor / skill layer) via the {@link publishNow}
+ * callback mechanism.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SocialPostManager();
+ * const draft = manager.createDraft({
+ *   seedId: 'my-agent',
+ *   content: 'Big announcement!',
+ *   platforms: ['twitter', 'linkedin'],
+ * });
+ *
+ * // Schedule for later
+ * manager.schedulePost(draft.id, '2026-03-10T15:00:00Z');
+ *
+ * // Or publish immediately
+ * await manager.publishNow(draft.id);
+ * ```
+ */
+export declare class SocialPostManager {
+    /** In-memory post store keyed by post ID. */
+    private readonly posts;
+    /**
+     * Optional publish handler injected by the consuming layer.
+     * Called for each platform when {@link publishNow} is invoked.
+     *
+     * When not provided, publishNow will mark all platforms as 'pending'
+     * and transition the post to 'publishing', leaving actual delivery
+     * to the caller.
+     */
+    private publishHandler?;
+    /**
+     * Register a platform publish handler.
+     *
+     * The handler receives the full post and a single platform string and must
+     * return a {@link SocialPostPlatformResult}. It is called once per platform
+     * during {@link publishNow}.
+     *
+     * @param handler - Async function that publishes content to a platform
+     */
+    setPublishHandler(handler: (post: SocialPost, platform: string) => Promise<SocialPostPlatformResult>): void;
+    /**
+     * Create a new draft post.
+     *
+     * If `input.schedule` is provided, the post is automatically transitioned
+     * to 'scheduled' status.
+     *
+     * @param input - Draft creation parameters
+     * @returns The newly created SocialPost in 'draft' (or 'scheduled') status
+     */
+    createDraft(input: CreateDraftInput): SocialPost;
+    /**
+     * Schedule a draft post for future publishing.
+     *
+     * @param postId    - ID of the post to schedule
+     * @param timestamp - ISO 8601 timestamp for desired publish time
+     * @returns The updated SocialPost in 'scheduled' status
+     * @throws {Error} If the post is not found or the transition is invalid
+     */
+    schedulePost(postId: string, timestamp: string): SocialPost;
+    /**
+     * Publish a post immediately.
+     *
+     * Transitions the post to 'publishing' and, if a publish handler is
+     * registered, invokes it for each target platform. After all platform
+     * results are collected, the post is transitioned to either 'published'
+     * (all succeeded) or 'error' (any failure).
+     *
+     * If no publish handler is registered, the post remains in 'publishing'
+     * status with all platform results set to 'pending'.
+     *
+     * @param postId - ID of the post to publish
+     * @returns The updated SocialPost after publish attempts
+     * @throws {Error} If the post is not found or the transition is invalid
+     */
+    publishNow(postId: string): Promise<SocialPost>;
+    /**
+     * Record a platform-specific publish result.
+     *
+     * Used by external publish handlers to report results asynchronously
+     * (e.g. webhook callbacks).
+     *
+     * @param postId   - ID of the post
+     * @param platform - Platform identifier
+     * @param result   - The platform result to record
+     * @returns The updated SocialPost
+     * @throws {Error} If the post is not found
+     */
+    markPlatformResult(postId: string, platform: string, result: SocialPostPlatformResult): SocialPost;
+    /**
+     * Retry a failed post.
+     *
+     * Transitions the post from 'error' to 'retry', increments the retry
+     * counter, and resets failed platform results to 'pending'.
+     *
+     * @param postId - ID of the post to retry
+     * @returns The updated SocialPost in 'retry' status
+     * @throws {Error} If the post is not found, the transition is invalid,
+     *                 or the maximum retry count has been reached
+     */
+    retryFailed(postId: string): SocialPost;
+    /**
+     * Retrieve a post by ID.
+     *
+     * @param postId - ID of the post to retrieve
+     * @returns The SocialPost if found, otherwise undefined
+     */
+    getPost(postId: string): SocialPost | undefined;
+    /**
+     * List posts with optional filtering by seed ID and/or status.
+     *
+     * @param seedId - Optional seed ID filter
+     * @param status - Optional status filter
+     * @returns Array of matching SocialPost objects
+     */
+    listPosts(seedId?: string, status?: SocialPostStatus): SocialPost[];
+    /**
+     * Get all scheduled posts whose scheduledAt timestamp has passed.
+     *
+     * Used by a polling loop or scheduler to find posts that are due for
+     * publishing.
+     *
+     * @returns Array of SocialPost objects that are due for publishing
+     */
+    getDuePosts(): SocialPost[];
+    /**
+     * Retrieve a post or throw if not found.
+     */
+    private requirePost;
+    /**
+     * Assert that a state transition is valid.
+     */
+    private assertTransition;
+    /**
+     * Initialize platform results with 'pending' status for each platform.
+     */
+    private initPlatformResults;
+}
+//# sourceMappingURL=SocialPostManager.d.ts.map

package/dist/social-posting/SocialPostManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialPostManager.d.ts","sourceRoot":"","sources":["../../src/social-posting/SocialPostManager.ts"],"names":[],"mappings":"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"}