@classytic/social 0.1.0

package/dist/contracts-Cdwa4zlg.d.mts

@@ -0,0 +1,121 @@
+import { g as UploadResult } from "./base-DBtKFiSX.mjs";
+
+//#region src/common/contracts.d.ts
+/**
+ * Provider authentication context. The shape varies by `authType`:
+ * - oauth2: `{ accessToken, ...tokens }` from a stored OAuthTokens record.
+ * - token / api_key: `{ accessToken: <bot/api token> }`.
+ *
+ * Providers may also need credentials (clientId/clientSecret) — pass via `creds`.
+ */
+interface ProviderAuth {
+  accessToken: string;
+  refreshToken?: string;
+  /** Provider-specific account / page / channel identifier. */
+  resourceId?: string;
+  /** Decrypted credential metadata (clientId, appSecret, etc.) for OAuth2 providers. */
+  creds?: Record<string, unknown>;
+  /** Extra OAuth fields (open_id, expires_at, etc.). */
+  extras?: Record<string, unknown>;
+}
+interface UnifiedMedia {
+  type: 'image' | 'video';
+  /** Public URL of the asset. Providers that require buffer uploads will fetch this. */
+  url: string;
+  /** Optional alt text / caption. */
+  alt?: string;
+}
+interface UnifiedPostInput {
+  /** Body text / caption. Required for text-only posts. */
+  text?: string;
+  /** Optional media attachments (single or multi-image / video). */
+  media?: UnifiedMedia[];
+  /** Optional URL for link-share posts. */
+  link?: string;
+  /** Optional schedule timestamp (ISO 8601). Provider must support scheduling. */
+  scheduledAt?: string | Date;
+  /** Provider-specific overrides — escape hatch for advanced consumers. */
+  raw?: Record<string, unknown>;
+}
+interface UnifiedPost {
+  /** Stable provider-side post identifier. */
+  id: string;
+  /** Permalink to the post on the provider's site. */
+  url?: string | null;
+  /** Body text / caption, when available. */
+  text?: string;
+  createdAt?: string;
+  /** Engagement metrics, when available. */
+  metrics?: {
+    likes?: number;
+    replies?: number;
+    shares?: number;
+    views?: number;
+  };
+  /** Original provider response for advanced consumers. */
+  raw?: Record<string, unknown>;
+}
+interface ListPostsOptions {
+  cursor?: string;
+  limit?: number;
+}
+/**
+ * Capability: create and manage posts.
+ */
+interface PostingProvider {
+  createPost(auth: ProviderAuth, input: UnifiedPostInput): Promise<UploadResult>;
+  deletePost?(auth: ProviderAuth, id: string): Promise<void>;
+  getPost?(auth: ProviderAuth, id: string): Promise<UnifiedPost>;
+  listPosts?(auth: ProviderAuth, opts?: ListPostsOptions): Promise<{
+    items: UnifiedPost[];
+    nextCursor?: string;
+  }>;
+}
+/**
+ * Capability: messaging (Telegram, WhatsApp, Twitter DMs).
+ */
+interface MessagingProvider {
+  sendTextMessage(auth: ProviderAuth, recipient: string, text: string): Promise<{
+    id: string;
+  }>;
+}
+/**
+ * Capability: media upload (video, photo).
+ */
+interface UploadingProvider {
+  uploadMedia(auth: ProviderAuth, media: UnifiedMedia, opts?: {
+    caption?: string;
+  }): Promise<UploadResult>;
+}
+/**
+ * Capability declaration — paired with `getCapabilities()` on each provider so
+ * consumers can introspect what each provider supports.
+ */
+interface ProviderCapabilities {
+  /** Authentication strategy. */
+  auth: 'oauth2' | 'token' | 'api_key';
+  /** Whether the provider supports text post publishing. */
+  posting: boolean;
+  /** Whether the provider supports media (photo/video) upload. */
+  upload: boolean;
+  /** Whether the provider supports messaging. */
+  messaging: boolean;
+  /** Whether the provider supports scheduled publishing. */
+  scheduling: boolean;
+  /** Whether the provider supports post deletion. */
+  deletion: boolean;
+  /** Whether the provider supports listing existing posts. */
+  listing: boolean;
+  /** Whether the provider supports analytics / insights. */
+  analytics: boolean;
+  /** Whether the provider supports sandbox/production environments. */
+  environments: boolean;
+  /** Whether OAuth uses PKCE. */
+  pkce: boolean;
+}
+declare function isPostingProvider(p: unknown): p is PostingProvider;
+declare function isMessagingProvider(p: unknown): p is MessagingProvider;
+declare function isUploadingProvider(p: unknown): p is UploadingProvider;
+//#endregion
+export { ProviderCapabilities as a, UnifiedPostInput as c, isPostingProvider as d, isUploadingProvider as f, ProviderAuth as i, UploadingProvider as l, MessagingProvider as n, UnifiedMedia as o, PostingProvider as r, UnifiedPost as s, ListPostsOptions as t, isMessagingProvider as u };
+//# sourceMappingURL=contracts-Cdwa4zlg.d.mts.map

package/dist/contracts-Cdwa4zlg.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts-Cdwa4zlg.d.mts","names":[],"sources":["../src/common/contracts.ts"],"mappings":";;;;AAmCA;;;;;;UAXiB,YAAA;EACf,WAAA;EACA,YAAA;EAiBe;EAff,UAAA;;EAEA,KAAA,GAAQ,MAAA;EAqBe;EAnBvB,MAAA,GAAS,MAAA;AAAA;AAAA,UAGM,YAAA;EACf,IAAA;EAWA;EATA,GAAA;EAWA;EATA,GAAA;AAAA;AAAA,UAGe,gBAAA;EAUT;EARN,IAAA;EAQY;EANZ,KAAA,GAAQ,YAAA;EASkB;EAP1B,IAAA;EAuBY;EArBZ,WAAA,YAAuB,IAAA;EASvB;EAPA,GAAA,GAAM,MAAA;AAAA;AAAA,UAGS,WAAA;EAUb;EARF,EAAA;EAUE;EARF,GAAA;EAYA;EAVA,IAAA;EACA,SAAA;EASY;EAPZ,OAAA;IACE,KAAA;IACA,OAAA;IACA,MAAA;IACA,KAAA;EAAA;EAc4B;EAX9B,GAAA,GAAM,MAAA;AAAA;AAAA,UAGS,gBAAA;EACf,MAAA;EACA,KAAA;AAAA;;;;UAMe,eAAA;EACf,UAAA,CAAW,IAAA,EAAM,YAAA,EAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA,CAAQ,YAAA;EACjE,UAAA,EAAY,IAAA,EAAM,YAAA,EAAc,EAAA,WAAa,OAAA;EAC7C,OAAA,EAAS,IAAA,EAAM,YAAA,EAAc,EAAA,WAAa,OAAA,CAAQ,WAAA;EAClD,SAAA,EAAW,IAAA,EAAM,YAAA,EAAc,IAAA,GAAO,gBAAA,GAAmB,OAAA;IAAU,KAAA,EAAO,WAAA;IAAe,UAAA;EAAA;AAAA;;;;UAM1E,iBAAA;EACf,eAAA,CAAgB,IAAA,EAAM,YAAA,EAAc,SAAA,UAAmB,IAAA,WAAe,OAAA;IAAU,EAAA;EAAA;AAAA;;;;UAMjE,iBAAA;EACf,WAAA,CAAY,IAAA,EAAM,YAAA,EAAc,KAAA,EAAO,YAAA,EAAc,IAAA;IAAS,OAAA;EAAA,IAAqB,OAAA,CAAQ,YAAA;AAAA;;;;;UAO5E,oBAAA;EArB0C;EAuBzD,IAAA;EAvB0E;EAyB1E,OAAA;EAzBmG;EA2BnG,MAAA;EArBe;EAuBf,SAAA;;EAEA,UAAA;EAxBA;EA0BA,QAAA;EA1BgB;EA4BhB,OAAA;EA5BuD;EA8BvD,SAAA;EA9BgF;EAgChF,YAAA;EAhCkF;EAkClF,IAAA;AAAA;AAAA,iBAKc,iBAAA,CAAkB,CAAA,YAAa,CAAA,IAAK,eAAA;AAAA,iBAIpC,mBAAA,CAAoB,CAAA,YAAa,CAAA,IAAK,iBAAA;AAAA,iBAItC,mBAAA,CAAoB,CAAA,YAAa,CAAA,IAAK,iBAAA"}

package/dist/contracts-lCa069IK.mjs

@@ -0,0 +1,221 @@
+import { t as SocialError } from "./errors-Cm6LeKf7.mjs";
+import { t as httpRequest } from "./http-DpcLSR1M.mjs";
+
+//#region src/common/oauth/oauth2.ts
+/**
+* Exchange an authorization code for an access token.
+*
+* The body is `application/x-www-form-urlencoded` per RFC 6749 §4.1.3. Client
+* credentials may be sent in the body (`client_secret`) or via Basic auth — the
+* latter is required by some providers (Reddit). Use `basicAuth: true` to opt in.
+*
+* @throws SocialError on HTTP failure (rate-limit, server error, parse error).
+*/
+async function oauth2ExchangeCode(provider, params) {
+	const body = {
+		grant_type: "authorization_code",
+		code: params.code,
+		redirect_uri: params.redirectUri,
+		client_id: params.clientId,
+		...params.codeVerifier ? { code_verifier: params.codeVerifier } : {},
+		...params.extra ?? {}
+	};
+	const headers = { ...params.headers ?? {} };
+	if (params.basicAuth && params.clientSecret) headers.Authorization = `Basic ${btoa(`${params.clientId}:${params.clientSecret}`)}`;
+	else if (params.clientSecret) body.client_secret = params.clientSecret;
+	const { data } = await httpRequest(provider, {
+		method: "POST",
+		url: params.tokenUrl,
+		urlencoded: body,
+		headers,
+		parseError: (raw) => {
+			if (raw && typeof raw === "object") {
+				const r = raw;
+				return {
+					message: r.error_description || r.error || "OAuth token exchange failed",
+					errorCode: r.error ?? null
+				};
+			}
+			return null;
+		}
+	});
+	return normalizeTokens(data);
+}
+/**
+* Refresh an access token using a refresh token (RFC 6749 §6).
+*/
+async function oauth2RefreshToken(provider, params) {
+	const body = {
+		grant_type: "refresh_token",
+		refresh_token: params.refreshToken,
+		client_id: params.clientId,
+		...params.extra ?? {}
+	};
+	const headers = { ...params.headers ?? {} };
+	if (params.basicAuth && params.clientSecret) headers.Authorization = `Basic ${btoa(`${params.clientId}:${params.clientSecret}`)}`;
+	else if (params.clientSecret) body.client_secret = params.clientSecret;
+	const { data } = await httpRequest(provider, {
+		method: "POST",
+		url: params.tokenUrl,
+		urlencoded: body,
+		headers,
+		parseError: (raw) => {
+			if (raw && typeof raw === "object") {
+				const r = raw;
+				return {
+					message: r.error_description || r.error || "OAuth token refresh failed",
+					errorCode: r.error ?? null
+				};
+			}
+			return null;
+		}
+	});
+	return normalizeTokens(data);
+}
+function normalizeTokens(raw) {
+	return {
+		access_token: raw.access_token,
+		refresh_token: raw.refresh_token,
+		expires_in: raw.expires_in,
+		token_type: raw.token_type ?? "Bearer",
+		scope: raw.scope,
+		...raw
+	};
+}
+/**
+* Build an OAuth 2.0 authorization URL (RFC 6749 §4.1.1).
+*/
+function buildAuthUrl(authUrl, params) {
+	const scope = Array.isArray(params.scope) ? params.scope.join(params.scopeSeparator ?? " ") : params.scope;
+	return `${authUrl}?${new URLSearchParams({
+		response_type: params.responseType ?? "code",
+		client_id: params.clientId,
+		redirect_uri: params.redirectUri,
+		state: params.state,
+		scope,
+		...params.codeChallenge ? {
+			code_challenge: params.codeChallenge,
+			code_challenge_method: params.codeChallengeMethod ?? "S256"
+		} : {},
+		...params.extra ?? {}
+	}).toString()}`;
+}
+
+//#endregion
+//#region src/common/paginate.ts
+function paginate(fetchPage, opts = {}) {
+	const maxPages = opts.maxPages ?? 100;
+	const maxItems = opts.maxItems;
+	async function* iterate() {
+		let cursor = void 0;
+		let pages = 0;
+		let yielded = 0;
+		do {
+			const page = await fetchPage(cursor);
+			for (const item of page.items) {
+				if (maxItems !== void 0 && yielded >= maxItems) return;
+				yield item;
+				yielded++;
+			}
+			cursor = page.nextCursor;
+			pages++;
+		} while (cursor && pages < maxPages);
+	}
+	return {
+		[Symbol.asyncIterator]: iterate,
+		async toArray() {
+			const out = [];
+			for await (const item of iterate()) out.push(item);
+			return out;
+		},
+		async take(n) {
+			const out = [];
+			for await (const item of iterate()) {
+				if (out.length >= n) break;
+				out.push(item);
+			}
+			return out;
+		}
+	};
+}
+
+//#endregion
+//#region src/common/security.ts
+/**
+* Security helpers used at provider boundaries.
+*/
+/**
+* Validate that a URL is safe to fetch on the server side.
+*
+* Rejects:
+* - Non-HTTP(S) schemes (file://, data://, gopher://, etc.)
+* - Localhost / loopback (127.0.0.0/8, ::1)
+* - RFC 1918 private ranges (10/8, 172.16/12, 192.168/16)
+* - Link-local (169.254/16) — blocks AWS/GCP metadata endpoints
+* - Multicast / reserved blocks
+*
+* **Note:** This is a literal-IP guard; it does not resolve DNS. For complete
+* protection (DNS-rebinding), validate again after resolution at fetch time.
+*/
+function assertPublicHttpUrl(provider, raw, context = "url") {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new SocialError(provider, `Invalid ${context}: not a valid URL`, { statusCode: 400 });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new SocialError(provider, `Invalid ${context}: only http(s) URLs are allowed`, { statusCode: 400 });
+	if (isLiteralPrivateHost(url.hostname)) throw new SocialError(provider, `Invalid ${context}: private/loopback addresses are not allowed`, { statusCode: 400 });
+	return url;
+}
+function isLiteralPrivateHost(hostname) {
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	if (host === "::1" || host === "0:0:0:0:0:0:0:1") return true;
+	if (host.startsWith("fe80:") || host.startsWith("fc") || host.startsWith("fd")) return true;
+	const m = host.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+	if (!m) return false;
+	const [, a, b] = m.map(Number);
+	if (a === 127) return true;
+	if (a === 10) return true;
+	if (a === 0) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 168) return true;
+	if (a >= 224) return true;
+	return false;
+}
+/**
+* Redact secrets from arbitrary objects for safe logging.
+* Replaces values for keys matching common secret patterns with `'[REDACTED]'`.
+*/
+function redactSecrets(input) {
+	const SECRET_KEY = /token|secret|password|api[_-]?key|credential|cookie|authorization/i;
+	function walk(v, depth) {
+		if (depth > 10 || v === null || v === void 0) return v;
+		if (Array.isArray(v)) return v.map((item) => walk(item, depth + 1));
+		if (typeof v === "object") {
+			const out = {};
+			for (const [k, val] of Object.entries(v)) out[k] = SECRET_KEY.test(k) ? "[REDACTED]" : walk(val, depth + 1);
+			return out;
+		}
+		return v;
+	}
+	return walk(input, 0);
+}
+
+//#endregion
+//#region src/common/contracts.ts
+function isPostingProvider(p) {
+	return !!p && typeof p.createPost === "function";
+}
+function isMessagingProvider(p) {
+	return !!p && typeof p.sendTextMessage === "function";
+}
+function isUploadingProvider(p) {
+	return !!p && typeof p.uploadMedia === "function";
+}
+
+//#endregion
+export { redactSecrets as a, oauth2ExchangeCode as c, assertPublicHttpUrl as i, oauth2RefreshToken as l, isPostingProvider as n, paginate as o, isUploadingProvider as r, buildAuthUrl as s, isMessagingProvider as t };
+//# sourceMappingURL=contracts-lCa069IK.mjs.map

package/dist/contracts-lCa069IK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts-lCa069IK.mjs","names":[],"sources":["../src/common/oauth/oauth2.ts","../src/common/paginate.ts","../src/common/security.ts","../src/common/contracts.ts"],"sourcesContent":["/**\n * Standard OAuth 2.0 helpers (RFC 6749).\n *\n * Covers code-for-token exchange and refresh-token grants for providers that\n * follow the spec closely (Twitter, Reddit, LinkedIn, TikTok). Provider-specific\n * variants (Meta two-step long-lived) live in `meta.ts`.\n */\n\nimport type { OAuthTokens } from '../../base.js';\nimport { httpRequest } from '../http.js';\n\nexport interface OAuth2ExchangeParams {\n  /** Token endpoint URL. */\n  tokenUrl: string;\n  /** Authorization code from the redirect callback. */\n  code: string;\n  clientId: string;\n  /** Required for confidential clients; sent via Basic auth or body. */\n  clientSecret?: string;\n  redirectUri: string;\n  /** PKCE verifier (S256 or plain). Required by Twitter, TikTok, etc. */\n  codeVerifier?: string;\n  /** Use HTTP Basic auth for client credentials (Reddit, Twitter confidential). */\n  basicAuth?: boolean;\n  /** Additional body params to merge in. */\n  extra?: Record<string, string>;\n  /** Additional headers (e.g., User-Agent for Reddit). */\n  headers?: Record<string, string>;\n}\n\nexport interface OAuth2RefreshParams {\n  tokenUrl: string;\n  refreshToken: string;\n  clientId: string;\n  clientSecret?: string;\n  basicAuth?: boolean;\n  extra?: Record<string, string>;\n  headers?: Record<string, string>;\n}\n\n/**\n * Exchange an authorization code for an access token.\n *\n * The body is `application/x-www-form-urlencoded` per RFC 6749 §4.1.3. Client\n * credentials may be sent in the body (`client_secret`) or via Basic auth — the\n * latter is required by some providers (Reddit). Use `basicAuth: true` to opt in.\n *\n * @throws SocialError on HTTP failure (rate-limit, server error, parse error).\n */\nexport async function oauth2ExchangeCode(\n  provider: string,\n  params: OAuth2ExchangeParams,\n): Promise<OAuthTokens> {\n  const body: Record<string, string> = {\n    grant_type: 'authorization_code',\n    code: params.code,\n    redirect_uri: params.redirectUri,\n    client_id: params.clientId,\n    ...(params.codeVerifier ? { code_verifier: params.codeVerifier } : {}),\n    ...(params.extra ?? {}),\n  };\n\n  const headers: Record<string, string> = { ...(params.headers ?? {}) };\n\n  if (params.basicAuth && params.clientSecret) {\n    headers.Authorization = `Basic ${btoa(`${params.clientId}:${params.clientSecret}`)}`;\n  } else if (params.clientSecret) {\n    body.client_secret = params.clientSecret;\n  }\n\n  const { data } = await httpRequest<Record<string, unknown>>(provider, {\n    method: 'POST',\n    url: params.tokenUrl,\n    urlencoded: body,\n    headers,\n    parseError: (raw) => {\n      if (raw && typeof raw === 'object') {\n        const r = raw as Record<string, unknown>;\n        return {\n          message: (r.error_description as string) || (r.error as string) || 'OAuth token exchange failed',\n          errorCode: (r.error as string) ?? null,\n        };\n      }\n      return null;\n    },\n  });\n\n  return normalizeTokens(data);\n}\n\n/**\n * Refresh an access token using a refresh token (RFC 6749 §6).\n */\nexport async function oauth2RefreshToken(\n  provider: string,\n  params: OAuth2RefreshParams,\n): Promise<OAuthTokens> {\n  const body: Record<string, string> = {\n    grant_type: 'refresh_token',\n    refresh_token: params.refreshToken,\n    client_id: params.clientId,\n    ...(params.extra ?? {}),\n  };\n\n  const headers: Record<string, string> = { ...(params.headers ?? {}) };\n\n  if (params.basicAuth && params.clientSecret) {\n    headers.Authorization = `Basic ${btoa(`${params.clientId}:${params.clientSecret}`)}`;\n  } else if (params.clientSecret) {\n    body.client_secret = params.clientSecret;\n  }\n\n  const { data } = await httpRequest<Record<string, unknown>>(provider, {\n    method: 'POST',\n    url: params.tokenUrl,\n    urlencoded: body,\n    headers,\n    parseError: (raw) => {\n      if (raw && typeof raw === 'object') {\n        const r = raw as Record<string, unknown>;\n        return {\n          message: (r.error_description as string) || (r.error as string) || 'OAuth token refresh failed',\n          errorCode: (r.error as string) ?? null,\n        };\n      }\n      return null;\n    },\n  });\n\n  return normalizeTokens(data);\n}\n\nfunction normalizeTokens(raw: Record<string, unknown>): OAuthTokens {\n  return {\n    access_token: raw.access_token as string,\n    refresh_token: raw.refresh_token as string | undefined,\n    expires_in: raw.expires_in as number | undefined,\n    token_type: (raw.token_type as string | undefined) ?? 'Bearer',\n    scope: raw.scope as string | undefined,\n    ...raw,\n  };\n}\n\n/**\n * Build an OAuth 2.0 authorization URL (RFC 6749 §4.1.1).\n */\nexport function buildAuthUrl(authUrl: string, params: {\n  clientId: string;\n  redirectUri: string;\n  state: string;\n  scope: string | string[];\n  /** Default `code` for authorization-code grant. */\n  responseType?: string;\n  /** Scope separator — space (default) or comma (Facebook). */\n  scopeSeparator?: ' ' | ',';\n  /** PKCE challenge (S256 or plain). */\n  codeChallenge?: string;\n  codeChallengeMethod?: 'S256' | 'plain';\n  /** Provider-specific extras (access_type, prompt, etc.). */\n  extra?: Record<string, string>;\n}): string {\n  const scope = Array.isArray(params.scope)\n    ? params.scope.join(params.scopeSeparator ?? ' ')\n    : params.scope;\n  const search = new URLSearchParams({\n    response_type: params.responseType ?? 'code',\n    client_id: params.clientId,\n    redirect_uri: params.redirectUri,\n    state: params.state,\n    scope,\n    ...(params.codeChallenge ? {\n      code_challenge: params.codeChallenge,\n      code_challenge_method: params.codeChallengeMethod ?? 'S256',\n    } : {}),\n    ...(params.extra ?? {}),\n  });\n  return `${authUrl}?${search.toString()}`;\n}\n","/**\n * Generic pagination helper.\n *\n * Wraps a per-page fetcher in an `AsyncIterable` so consumers can do:\n *\n *   for await (const post of paginate(fetchPage)) { ... }\n *\n * Use `.toArray()` for the simple case, or `.take(n)` to bound results.\n */\n\nexport interface Page<T> {\n  items: T[];\n  /** Opaque cursor for the next page, or `undefined` when exhausted. */\n  nextCursor?: string;\n}\n\nexport interface PaginateOptions {\n  /** Hard cap on items returned across pages. */\n  maxItems?: number;\n  /** Hard cap on page fetches (defense against infinite loops). Default 100. */\n  maxPages?: number;\n}\n\nexport interface PaginatedIterable<T> extends AsyncIterable<T> {\n  toArray(): Promise<T[]>;\n  take(n: number): Promise<T[]>;\n}\n\nexport function paginate<T>(\n  fetchPage: (cursor: string | undefined) => Promise<Page<T>>,\n  opts: PaginateOptions = {},\n): PaginatedIterable<T> {\n  const maxPages = opts.maxPages ?? 100;\n  const maxItems = opts.maxItems;\n\n  async function* iterate(): AsyncGenerator<T> {\n    let cursor: string | undefined = undefined;\n    let pages = 0;\n    let yielded = 0;\n    do {\n      const page = await fetchPage(cursor);\n      for (const item of page.items) {\n        if (maxItems !== undefined && yielded >= maxItems) return;\n        yield item;\n        yielded++;\n      }\n      cursor = page.nextCursor;\n      pages++;\n    } while (cursor && pages < maxPages);\n  }\n\n  const iterable: PaginatedIterable<T> = {\n    [Symbol.asyncIterator]: iterate,\n    async toArray() {\n      const out: T[] = [];\n      for await (const item of iterate()) out.push(item);\n      return out;\n    },\n    async take(n: number) {\n      const out: T[] = [];\n      for await (const item of iterate()) {\n        if (out.length >= n) break;\n        out.push(item);\n      }\n      return out;\n    },\n  };\n  return iterable;\n}\n","/**\n * Security helpers used at provider boundaries.\n */\n\nimport { SocialError } from '../errors.js';\n\n/**\n * Validate that a URL is safe to fetch on the server side.\n *\n * Rejects:\n * - Non-HTTP(S) schemes (file://, data://, gopher://, etc.)\n * - Localhost / loopback (127.0.0.0/8, ::1)\n * - RFC 1918 private ranges (10/8, 172.16/12, 192.168/16)\n * - Link-local (169.254/16) — blocks AWS/GCP metadata endpoints\n * - Multicast / reserved blocks\n *\n * **Note:** This is a literal-IP guard; it does not resolve DNS. For complete\n * protection (DNS-rebinding), validate again after resolution at fetch time.\n */\nexport function assertPublicHttpUrl(provider: string, raw: string, context = 'url'): URL {\n  let url: URL;\n  try {\n    url = new URL(raw);\n  } catch {\n    throw new SocialError(provider, `Invalid ${context}: not a valid URL`, { statusCode: 400 });\n  }\n  if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n    throw new SocialError(provider, `Invalid ${context}: only http(s) URLs are allowed`, { statusCode: 400 });\n  }\n  if (isLiteralPrivateHost(url.hostname)) {\n    throw new SocialError(provider, `Invalid ${context}: private/loopback addresses are not allowed`, { statusCode: 400 });\n  }\n  return url;\n}\n\nfunction isLiteralPrivateHost(hostname: string): boolean {\n  const host = hostname.toLowerCase().replace(/^\\[|\\]$/g, '');\n  if (host === 'localhost' || host.endsWith('.localhost')) return true;\n  // IPv6 loopback / link-local / unique-local\n  if (host === '::1' || host === '0:0:0:0:0:0:0:1') return true;\n  if (host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd')) return true;\n  // IPv4 dotted quad?\n  const m = host.match(/^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$/);\n  if (!m) return false;\n  const [, a, b] = m.map(Number) as [number, number, number, number, number];\n  if (a === 127) return true;            // 127.0.0.0/8\n  if (a === 10) return true;             // 10.0.0.0/8\n  if (a === 0) return true;              // 0.0.0.0/8\n  if (a === 169 && b === 254) return true; // 169.254.0.0/16 (link-local, AWS metadata)\n  if (a === 172 && b! >= 16 && b! <= 31) return true; // 172.16.0.0/12\n  if (a === 192 && b === 168) return true; // 192.168.0.0/16\n  if (a >= 224) return true;             // 224.0.0.0/4 multicast, 240.0.0.0/4 reserved\n  return false;\n}\n\n/**\n * Redact secrets from arbitrary objects for safe logging.\n * Replaces values for keys matching common secret patterns with `'[REDACTED]'`.\n */\nexport function redactSecrets(input: unknown): unknown {\n  const SECRET_KEY = /token|secret|password|api[_-]?key|credential|cookie|authorization/i;\n  function walk(v: unknown, depth: number): unknown {\n    if (depth > 10 || v === null || v === undefined) return v;\n    if (Array.isArray(v)) return v.map(item => walk(item, depth + 1));\n    if (typeof v === 'object') {\n      const out: Record<string, unknown> = {};\n      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {\n        out[k] = SECRET_KEY.test(k) ? '[REDACTED]' : walk(val, depth + 1);\n      }\n      return out;\n    }\n    return v;\n  }\n  return walk(input, 0);\n}\n","/**\n * Unified provider contracts.\n *\n * These interfaces define a *thin façade* over per-provider methods so that\n * registry consumers can dispatch generically without knowing each provider's\n * exact signature. Providers opt into capabilities by implementing the matching\n * interface.\n *\n * Example:\n *   const provider = registry.getProvider('facebook');\n *   if (isPostingProvider(provider)) {\n *     await provider.createPost(auth, { text: 'hello' });\n *   }\n */\n\nimport type { OAuthTokens, UploadResult } from '../base.js';\n\n/**\n * Provider authentication context. The shape varies by `authType`:\n * - oauth2: `{ accessToken, ...tokens }` from a stored OAuthTokens record.\n * - token / api_key: `{ accessToken: <bot/api token> }`.\n *\n * Providers may also need credentials (clientId/clientSecret) — pass via `creds`.\n */\nexport interface ProviderAuth {\n  accessToken: string;\n  refreshToken?: string;\n  /** Provider-specific account / page / channel identifier. */\n  resourceId?: string;\n  /** Decrypted credential metadata (clientId, appSecret, etc.) for OAuth2 providers. */\n  creds?: Record<string, unknown>;\n  /** Extra OAuth fields (open_id, expires_at, etc.). */\n  extras?: Record<string, unknown>;\n}\n\nexport interface UnifiedMedia {\n  type: 'image' | 'video';\n  /** Public URL of the asset. Providers that require buffer uploads will fetch this. */\n  url: string;\n  /** Optional alt text / caption. */\n  alt?: string;\n}\n\nexport interface UnifiedPostInput {\n  /** Body text / caption. Required for text-only posts. */\n  text?: string;\n  /** Optional media attachments (single or multi-image / video). */\n  media?: UnifiedMedia[];\n  /** Optional URL for link-share posts. */\n  link?: string;\n  /** Optional schedule timestamp (ISO 8601). Provider must support scheduling. */\n  scheduledAt?: string | Date;\n  /** Provider-specific overrides — escape hatch for advanced consumers. */\n  raw?: Record<string, unknown>;\n}\n\nexport interface UnifiedPost {\n  /** Stable provider-side post identifier. */\n  id: string;\n  /** Permalink to the post on the provider's site. */\n  url?: string | null;\n  /** Body text / caption, when available. */\n  text?: string;\n  createdAt?: string;\n  /** Engagement metrics, when available. */\n  metrics?: {\n    likes?: number;\n    replies?: number;\n    shares?: number;\n    views?: number;\n  };\n  /** Original provider response for advanced consumers. */\n  raw?: Record<string, unknown>;\n}\n\nexport interface ListPostsOptions {\n  cursor?: string;\n  limit?: number;\n}\n\n/**\n * Capability: create and manage posts.\n */\nexport interface PostingProvider {\n  createPost(auth: ProviderAuth, input: UnifiedPostInput): Promise<UploadResult>;\n  deletePost?(auth: ProviderAuth, id: string): Promise<void>;\n  getPost?(auth: ProviderAuth, id: string): Promise<UnifiedPost>;\n  listPosts?(auth: ProviderAuth, opts?: ListPostsOptions): Promise<{ items: UnifiedPost[]; nextCursor?: string }>;\n}\n\n/**\n * Capability: messaging (Telegram, WhatsApp, Twitter DMs).\n */\nexport interface MessagingProvider {\n  sendTextMessage(auth: ProviderAuth, recipient: string, text: string): Promise<{ id: string }>;\n}\n\n/**\n * Capability: media upload (video, photo).\n */\nexport interface UploadingProvider {\n  uploadMedia(auth: ProviderAuth, media: UnifiedMedia, opts?: { caption?: string }): Promise<UploadResult>;\n}\n\n/**\n * Capability declaration — paired with `getCapabilities()` on each provider so\n * consumers can introspect what each provider supports.\n */\nexport interface ProviderCapabilities {\n  /** Authentication strategy. */\n  auth: 'oauth2' | 'token' | 'api_key';\n  /** Whether the provider supports text post publishing. */\n  posting: boolean;\n  /** Whether the provider supports media (photo/video) upload. */\n  upload: boolean;\n  /** Whether the provider supports messaging. */\n  messaging: boolean;\n  /** Whether the provider supports scheduled publishing. */\n  scheduling: boolean;\n  /** Whether the provider supports post deletion. */\n  deletion: boolean;\n  /** Whether the provider supports listing existing posts. */\n  listing: boolean;\n  /** Whether the provider supports analytics / insights. */\n  analytics: boolean;\n  /** Whether the provider supports sandbox/production environments. */\n  environments: boolean;\n  /** Whether OAuth uses PKCE. */\n  pkce: boolean;\n}\n\n// ─── Type guards ────────────────────────────────────────────────────────────\n\nexport function isPostingProvider(p: unknown): p is PostingProvider {\n  return !!p && typeof (p as { createPost?: unknown }).createPost === 'function';\n}\n\nexport function isMessagingProvider(p: unknown): p is MessagingProvider {\n  return !!p && typeof (p as { sendTextMessage?: unknown }).sendTextMessage === 'function';\n}\n\nexport function isUploadingProvider(p: unknown): p is UploadingProvider {\n  return !!p && typeof (p as { uploadMedia?: unknown }).uploadMedia === 'function';\n}\n\n// Re-export for clarity\nexport type { OAuthTokens, UploadResult };\n"],"mappings":"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"}