@opencoredev/social-sdk 0.2.1 → 0.4.0

package/dist/server/webhooks.d.ts

@@ -1,9 +1,13 @@
 import type { JsonObject } from "../core/types.js";
+export type WebhookVerificationMethod = "hmac-sha1" | "hmac-sha256" | "hmac-sha384" | "hmac-sha512" | "shared-secret-header";
 export interface VerifiedWebhook {
     readonly valid: true;
-    readonly method: "hmac-sha256" | "shared-secret-header";
+    readonly method: WebhookVerificationMethod;
     readonly bodyAuthenticated: boolean;
-    readonly signedTimestamp: false;
+    /** True only when the provider signs a delivery timestamp together with the body. */
+    readonly signedTimestamp: boolean;
+    /** ISO time of the signed delivery timestamp, when the provider signs one. */
+    readonly signedAt?: string;
 }
 export declare function verifyZernioWebhook(input: {
     secret: string;
@@ -21,7 +25,7 @@ export interface SocialEvent {
     readonly version: 1;
     readonly id: string;
     readonly backend: string;
-    readonly provider: "zernio" | "post-for-me";
+    readonly provider: "zernio" | "post-for-me" | DirectWebhookPlatform;
     readonly type: "publication.updated" | "post.removed" | "backend-record.deleted" | "account.updated" | "message.received" | "comment.received" | "unknown";
     readonly identity: "provider-event-id" | "body-digest";
     readonly originalType: string;
@@ -55,3 +59,132 @@ export declare function acceptWebhook(input: {
     state: "accepted" | "duplicate";
     quarantined: boolean;
 }>;
+export type DirectWebhookPlatform = "instagram" | "threads" | "x" | "youtube" | "tiktok" | "linkedin";
+/** Framework-neutral answer to a provider GET handshake. */
+export interface WebhookChallengeResponse {
+    readonly status: 200;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+export interface XWebhookChallengeResponse extends WebhookChallengeResponse {
+    readonly responseToken: string;
+}
+export interface YouTubeWebhookChallengeResponse extends WebhookChallengeResponse {
+    readonly mode: "subscribe" | "unsubscribe";
+    readonly topic: string;
+    readonly leaseSeconds?: number;
+}
+/**
+ * Verify a Meta webhook POST for Instagram or Threads. Meta signs the raw body with
+ * HMAC-SHA256 using the app secret and sends `X-Hub-Signature-256: sha256=<hex>`.
+ */
+export declare function verifyMetaWebhook(input: {
+    secret: string;
+    headers: Headers;
+    body: Uint8Array;
+    maxBytes?: number;
+}): Promise<VerifiedWebhook>;
+/**
+ * Answer Meta's GET verification request. The verify token is compared in constant
+ * time and only a bounded, token-safe `hub.challenge` is echoed.
+ */
+export declare function answerMetaWebhookChallenge(input: {
+    verifyToken: string;
+    query: URLSearchParams;
+}): Promise<WebhookChallengeResponse>;
+/**
+ * Verify an X webhook POST. X signs the raw body with HMAC-SHA256 and sends
+ * `sha256=<base64>` in `X-Twitter-Webhooks-Signature-OAuth2` (OAuth 2.0 client secret)
+ * or the legacy `X-Twitter-Webhooks-Signature` (OAuth 1.0 consumer secret). When the
+ * OAuth 2.0 header is present it alone decides; the legacy header is checked only when
+ * the OAuth 2.0 header is absent. Pass the secret that matches the header X sends.
+ */
+export declare function verifyXWebhook(input: {
+    secret: string;
+    headers: Headers;
+    body: Uint8Array;
+    maxBytes?: number;
+}): Promise<VerifiedWebhook>;
+/**
+ * Answer X's CRC GET request with `{"response_token":"sha256=<base64>"}`, an
+ * HMAC-SHA256 of `crc_token` keyed with the same secret used for signatures.
+ */
+export declare function answerXWebhookChallenge(input: {
+    secret: string;
+    query: URLSearchParams;
+}): Promise<XWebhookChallengeResponse>;
+/**
+ * Verify a YouTube push notification delivered through the PubSubHubbub hub. The
+ * hub only signs deliveries when the subscription was created with `hub.secret`; it
+ * sends `X-Hub-Signature: <method>=<hex>`, and the reported method is returned.
+ */
+export declare function verifyYouTubeWebhook(input: {
+    secret: string;
+    headers: Headers;
+    body: Uint8Array;
+    maxBytes?: number;
+}): Promise<VerifiedWebhook>;
+/**
+ * Answer the hub's GET verification of intent. The topic must be one the
+ * application is currently subscribing to or unsubscribing from; otherwise this
+ * throws `not_found`, which WebSub expects as an HTTP 404.
+ */
+export declare function answerYouTubeWebhookChallenge(input: {
+    query: URLSearchParams;
+    topics: readonly string[];
+}): YouTubeWebhookChallengeResponse;
+/**
+ * Verify a TikTok webhook POST. `TikTok-Signature: t=<unix seconds>,s=<hex>` carries an
+ * HMAC-SHA256 of `<t>.<raw body>` keyed with the app's client secret. TikTok leaves
+ * the replay window to the receiver; this defaults to 300 seconds.
+ */
+export declare function verifyTikTokWebhook(input: {
+    secret: string;
+    headers: Headers;
+    body: Uint8Array;
+    maxBytes?: number;
+    toleranceSeconds?: number;
+    now?: () => Date;
+}): Promise<VerifiedWebhook>;
+/**
+ * Verify a LinkedIn webhook POST. `X-LI-Signature` carries only the lowercase hex
+ * HMAC-SHA256 of the literal `hmacsha256=` followed by the raw body, keyed with the
+ * app's client secret. LinkedIn sends no signed timestamp.
+ */
+export declare function verifyLinkedInWebhook(input: {
+    secret: string;
+    headers: Headers;
+    body: Uint8Array;
+    maxBytes?: number;
+}): Promise<VerifiedWebhook>;
+export interface LinkedInWebhookChallengeResponse extends WebhookChallengeResponse {
+    readonly challengeCode: string;
+    readonly challengeResponse: string;
+    readonly applicationId?: string;
+}
+/**
+ * Answer LinkedIn's GET validation, which LinkedIn repeats every 2 hours. The
+ * response is `{ challengeCode, challengeResponse }`, where `challengeResponse` is the
+ * lowercase hex HMAC-SHA256 of `challengeCode` keyed with the client secret. For
+ * parent-child applications LinkedIn adds `applicationId`; pass `secretForApplication`
+ * to pick that application's client secret. An unknown application is refused.
+ */
+export declare function answerLinkedInWebhookChallenge(input: {
+    secret: string;
+    query: URLSearchParams;
+    secretForApplication?: (applicationId: string) => string | undefined;
+}): Promise<LinkedInWebhookChallengeResponse>;
+/**
+ * Decode a verified direct-platform delivery into one normalized event. A single
+ * delivery can batch several notifications (Meta batches up to 1000 updates); the
+ * event keeps them all in `data` and reports a specific `type` only when every
+ * notification maps to the same type. None of these platforms sends a delivery ID,
+ * so identity is always an exact-body digest.
+ */
+export declare function decodePlatformWebhook(input: {
+    platform: DirectWebhookPlatform;
+    backend: string;
+    body: Uint8Array;
+    receivedAt?: string;
+    maxBytes?: number;
+}): Promise<SocialEvent>;