@adeli/sdk 0.0.0-stage → 0.1.0

package/dist/helpers/index.d.cts

@@ -0,0 +1,207 @@
+import { R as RequestOptions, A as ApiResponse } from '../uploads-MGVSU99R.cjs';
+import { P as ProfilePath, C as ConnectionSession, F as FacebookPostStatusResponse, I as InstagramPostStatusResponse, T as TikTokPostStatusResponse, Y as YouTubeVideoStatusResponse, a as CommentsQuery, b as CommentsResponse } from '../comments-C_vDnwix.cjs';
+
+type PublishStatusQuery = {
+    readonly accountId: string;
+    readonly profileId?: string;
+    readonly publishId: string;
+};
+type InstagramStatusQuery = {
+    readonly jobId: string;
+    readonly profileId?: string;
+};
+type VideoStatusQuery = {
+    readonly accountId: string;
+    readonly profileId?: string;
+    readonly videoId: string;
+};
+/** A bounded polling deadline and delay. Both values are required to make the side effect explicit. */
+interface PollingOptions {
+    readonly timeoutMs: number;
+    readonly intervalMs: number;
+    readonly signal?: AbortSignal;
+}
+type ConnectionMethod = (args: {
+    readonly path: ProfilePath & {
+        readonly connectionSessionId: string;
+    };
+}, options?: RequestOptions) => Promise<ApiResponse<ConnectionSession>>;
+type ConnectionPollingClient = {
+    readonly profiles: {
+        readonly getConnection: ConnectionMethod;
+    };
+} | {
+    readonly getConnection: ConnectionMethod;
+};
+type InstagramMethod = (args: {
+    readonly query: InstagramStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<InstagramPostStatusResponse>>;
+type TikTokMethod = (args: {
+    readonly query: PublishStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<TikTokPostStatusResponse>>;
+type FacebookMethod = (args: {
+    readonly query: PublishStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<FacebookPostStatusResponse>>;
+type YouTubeMethod = (args: {
+    readonly query: VideoStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<YouTubeVideoStatusResponse>>;
+type InstagramPollingClient = {
+    readonly posts: {
+        readonly getInstagramPostStatus: InstagramMethod;
+    };
+} | {
+    readonly getInstagramPostStatus: InstagramMethod;
+};
+type TikTokPollingClient = {
+    readonly posts: {
+        readonly getTikTokPostStatus: TikTokMethod;
+    };
+} | {
+    readonly getTikTokPostStatus: TikTokMethod;
+};
+type FacebookPollingClient = {
+    readonly posts: {
+        readonly getFacebookPostStatus: FacebookMethod;
+    };
+} | {
+    readonly getFacebookPostStatus: FacebookMethod;
+};
+type YouTubePollingClient = {
+    readonly posts: {
+        readonly getYouTubeVideoStatus: YouTubeMethod;
+    };
+} | {
+    readonly getYouTubeVideoStatus: YouTubeMethod;
+};
+/** A convenience structural type for clients that expose all post status methods under resources. */
+type PostPollingClient = {
+    readonly posts: {
+        readonly getInstagramPostStatus: InstagramMethod;
+        readonly getTikTokPostStatus: TikTokMethod;
+        readonly getFacebookPostStatus: FacebookMethod;
+        readonly getYouTubeVideoStatus: YouTubeMethod;
+    };
+};
+/** Poll a typed connection session; Facebook Page selection can require a dashboard handoff. */
+declare function waitForConnection(client: ConnectionPollingClient, args: {
+    readonly path: ProfilePath & {
+        readonly connectionSessionId: string;
+    };
+}, options: PollingOptions): Promise<ApiResponse<ConnectionSession>>;
+/** Poll durable Instagram publication through published, failed, or uncertain outcome. */
+declare function waitForInstagramPost(client: InstagramPollingClient, args: {
+    readonly query: InstagramStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<InstagramPostStatusResponse>>;
+/** Poll TikTok processing. SEND_TO_USER_INBOX is not a public publication. */
+declare function waitForTikTokPost(client: TikTokPollingClient, args: {
+    readonly query: PublishStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<TikTokPostStatusResponse>>;
+/** Poll Facebook video processing; Page selection is outside this status endpoint. */
+declare function waitForFacebookPost(client: FacebookPollingClient, args: {
+    readonly query: PublishStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<FacebookPostStatusResponse>>;
+/** Poll YouTube processing. Published means processing completed, not public visibility. */
+declare function waitForYouTubeVideo(client: YouTubePollingClient, args: {
+    readonly query: VideoStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<YouTubeVideoStatusResponse>>;
+
+type CommentIteratorQuery = Omit<CommentsQuery, 'platform'> & {
+    readonly platform: 'tiktok' | 'youtube';
+};
+interface CommentsClient {
+    readonly comments: {
+        listComments(args: {
+            readonly query: CommentsQuery;
+        }, options?: RequestOptions): Promise<ApiResponse<CommentsResponse>>;
+    };
+}
+interface CommentIteratorOptions {
+    /** Maximum number of requests. The default is deliberately finite. */
+    readonly maxPages?: number;
+    /** Total wall-clock budget for all pages, including request time. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Yield complete page responses; `complete` describes cache freshness, not pagination. */
+declare function iterateCommentPages(client: CommentsClient, args: {
+    readonly query: CommentIteratorQuery;
+}, options?: CommentIteratorOptions): AsyncGenerator<ApiResponse<CommentsResponse>>;
+/** Yield the original comment records without normalizing provider fields. */
+declare function iterateComments(client: CommentsClient, args: {
+    readonly query: CommentIteratorQuery;
+}, options?: CommentIteratorOptions): AsyncGenerator<CommentsResponse['comments'][number]>;
+
+/** The raw request body exactly as received. Verify before parsing; re-serialized JSON will not match. */
+type WebhookPayload = string | Uint8Array;
+interface VerifyWebhookSignatureInput {
+    /** The raw request body. */
+    readonly payload: WebhookPayload;
+    /** The `Adeli-Signature` header: `t=<unix seconds>,v1=<hex HMAC-SHA256>`. */
+    readonly header: string | null | undefined;
+    /** The webhook's signing secret, returned once by `createWebhook`. */
+    readonly secret: string;
+    /** Maximum age (or clock skew) of the signed timestamp. Defaults to 300 seconds. */
+    readonly toleranceSeconds?: number;
+    /** Current time in unix seconds, for tests. Defaults to the system clock. */
+    readonly now?: number;
+}
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * Check an `Adeli-Signature` header against the raw body. Returns false for a
+ * malformed header, a timestamp outside the tolerance, or a signature mismatch;
+ * the comparison is constant-time. Throws only for a missing secret or an
+ * invalid tolerance, which are configuration mistakes rather than bad deliveries.
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
+interface WebhookEventEnvelope {
+    /** Stable per provider event; deduplicate redeliveries on it. */
+    readonly id: string;
+    readonly createdAt: string;
+    readonly profileId: string;
+    readonly accountId: string;
+}
+interface CommentCreatedEvent extends WebhookEventEnvelope {
+    readonly type: 'comment.created';
+    readonly platform: 'instagram';
+    readonly data: {
+        readonly commentId: string;
+        readonly mediaId: string;
+        readonly parentId: string | null;
+        readonly text: string;
+        readonly from: {
+            readonly id: string | null;
+            readonly username: string | null;
+        };
+        /** True when the connected account wrote the comment itself. */
+        readonly isSelf: boolean;
+    };
+}
+interface MessagePostbackEvent extends WebhookEventEnvelope {
+    readonly type: 'message.postback';
+    readonly platform: 'instagram';
+    readonly data: {
+        /** The person's Instagram-scoped id; reply with `sendInstagramMessage({ recipient: { id: senderId } })`. */
+        readonly senderId: string;
+        readonly payload: string;
+        readonly title: string | null;
+        readonly messageId: string | null;
+    };
+}
+/** An event type (or platform) this SDK version does not know yet. `eventType` keeps the wire `type`. */
+interface UnknownWebhookEvent extends WebhookEventEnvelope {
+    readonly type: 'unknown';
+    readonly eventType: string;
+    readonly platform: string;
+    readonly data: unknown;
+}
+type WebhookEvent = CommentCreatedEvent | MessagePostbackEvent | UnknownWebhookEvent;
+type WebhookEventType = Exclude<WebhookEvent['type'], 'unknown'>;
+/**
+ * Parse a verified webhook body into a typed event. Known types are validated
+ * field by field; an unrecognised type parses as `type: 'unknown'` so new event
+ * types stay additive. Throws `MalformedResponseError` for invalid JSON, a
+ * missing envelope field, or a known event whose data does not match.
+ */
+declare function parseWebhookEvent(payload: WebhookPayload): WebhookEvent;
+
+export { type CommentCreatedEvent, type CommentIteratorOptions, type CommentIteratorQuery, type CommentsClient, type ConnectionPollingClient, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type FacebookPollingClient, type InstagramPollingClient, type MessagePostbackEvent, type PollingOptions, type PostPollingClient, type TikTokPollingClient, type UnknownWebhookEvent, type VerifyWebhookSignatureInput, type WebhookEvent, type WebhookEventType, type WebhookPayload, type YouTubePollingClient, iterateCommentPages, iterateComments, parseWebhookEvent, verifyWebhookSignature, waitForConnection, waitForFacebookPost, waitForInstagramPost, waitForTikTokPost, waitForYouTubeVideo };

package/dist/helpers/index.d.ts

@@ -0,0 +1,207 @@
+import { R as RequestOptions, A as ApiResponse } from '../uploads-MGVSU99R.js';
+import { P as ProfilePath, C as ConnectionSession, F as FacebookPostStatusResponse, I as InstagramPostStatusResponse, T as TikTokPostStatusResponse, Y as YouTubeVideoStatusResponse, a as CommentsQuery, b as CommentsResponse } from '../comments-Dx3195Ty.js';
+
+type PublishStatusQuery = {
+    readonly accountId: string;
+    readonly profileId?: string;
+    readonly publishId: string;
+};
+type InstagramStatusQuery = {
+    readonly jobId: string;
+    readonly profileId?: string;
+};
+type VideoStatusQuery = {
+    readonly accountId: string;
+    readonly profileId?: string;
+    readonly videoId: string;
+};
+/** A bounded polling deadline and delay. Both values are required to make the side effect explicit. */
+interface PollingOptions {
+    readonly timeoutMs: number;
+    readonly intervalMs: number;
+    readonly signal?: AbortSignal;
+}
+type ConnectionMethod = (args: {
+    readonly path: ProfilePath & {
+        readonly connectionSessionId: string;
+    };
+}, options?: RequestOptions) => Promise<ApiResponse<ConnectionSession>>;
+type ConnectionPollingClient = {
+    readonly profiles: {
+        readonly getConnection: ConnectionMethod;
+    };
+} | {
+    readonly getConnection: ConnectionMethod;
+};
+type InstagramMethod = (args: {
+    readonly query: InstagramStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<InstagramPostStatusResponse>>;
+type TikTokMethod = (args: {
+    readonly query: PublishStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<TikTokPostStatusResponse>>;
+type FacebookMethod = (args: {
+    readonly query: PublishStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<FacebookPostStatusResponse>>;
+type YouTubeMethod = (args: {
+    readonly query: VideoStatusQuery;
+}, options?: RequestOptions) => Promise<ApiResponse<YouTubeVideoStatusResponse>>;
+type InstagramPollingClient = {
+    readonly posts: {
+        readonly getInstagramPostStatus: InstagramMethod;
+    };
+} | {
+    readonly getInstagramPostStatus: InstagramMethod;
+};
+type TikTokPollingClient = {
+    readonly posts: {
+        readonly getTikTokPostStatus: TikTokMethod;
+    };
+} | {
+    readonly getTikTokPostStatus: TikTokMethod;
+};
+type FacebookPollingClient = {
+    readonly posts: {
+        readonly getFacebookPostStatus: FacebookMethod;
+    };
+} | {
+    readonly getFacebookPostStatus: FacebookMethod;
+};
+type YouTubePollingClient = {
+    readonly posts: {
+        readonly getYouTubeVideoStatus: YouTubeMethod;
+    };
+} | {
+    readonly getYouTubeVideoStatus: YouTubeMethod;
+};
+/** A convenience structural type for clients that expose all post status methods under resources. */
+type PostPollingClient = {
+    readonly posts: {
+        readonly getInstagramPostStatus: InstagramMethod;
+        readonly getTikTokPostStatus: TikTokMethod;
+        readonly getFacebookPostStatus: FacebookMethod;
+        readonly getYouTubeVideoStatus: YouTubeMethod;
+    };
+};
+/** Poll a typed connection session; Facebook Page selection can require a dashboard handoff. */
+declare function waitForConnection(client: ConnectionPollingClient, args: {
+    readonly path: ProfilePath & {
+        readonly connectionSessionId: string;
+    };
+}, options: PollingOptions): Promise<ApiResponse<ConnectionSession>>;
+/** Poll durable Instagram publication through published, failed, or uncertain outcome. */
+declare function waitForInstagramPost(client: InstagramPollingClient, args: {
+    readonly query: InstagramStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<InstagramPostStatusResponse>>;
+/** Poll TikTok processing. SEND_TO_USER_INBOX is not a public publication. */
+declare function waitForTikTokPost(client: TikTokPollingClient, args: {
+    readonly query: PublishStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<TikTokPostStatusResponse>>;
+/** Poll Facebook video processing; Page selection is outside this status endpoint. */
+declare function waitForFacebookPost(client: FacebookPollingClient, args: {
+    readonly query: PublishStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<FacebookPostStatusResponse>>;
+/** Poll YouTube processing. Published means processing completed, not public visibility. */
+declare function waitForYouTubeVideo(client: YouTubePollingClient, args: {
+    readonly query: VideoStatusQuery;
+}, options: PollingOptions): Promise<ApiResponse<YouTubeVideoStatusResponse>>;
+
+type CommentIteratorQuery = Omit<CommentsQuery, 'platform'> & {
+    readonly platform: 'tiktok' | 'youtube';
+};
+interface CommentsClient {
+    readonly comments: {
+        listComments(args: {
+            readonly query: CommentsQuery;
+        }, options?: RequestOptions): Promise<ApiResponse<CommentsResponse>>;
+    };
+}
+interface CommentIteratorOptions {
+    /** Maximum number of requests. The default is deliberately finite. */
+    readonly maxPages?: number;
+    /** Total wall-clock budget for all pages, including request time. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Yield complete page responses; `complete` describes cache freshness, not pagination. */
+declare function iterateCommentPages(client: CommentsClient, args: {
+    readonly query: CommentIteratorQuery;
+}, options?: CommentIteratorOptions): AsyncGenerator<ApiResponse<CommentsResponse>>;
+/** Yield the original comment records without normalizing provider fields. */
+declare function iterateComments(client: CommentsClient, args: {
+    readonly query: CommentIteratorQuery;
+}, options?: CommentIteratorOptions): AsyncGenerator<CommentsResponse['comments'][number]>;
+
+/** The raw request body exactly as received. Verify before parsing; re-serialized JSON will not match. */
+type WebhookPayload = string | Uint8Array;
+interface VerifyWebhookSignatureInput {
+    /** The raw request body. */
+    readonly payload: WebhookPayload;
+    /** The `Adeli-Signature` header: `t=<unix seconds>,v1=<hex HMAC-SHA256>`. */
+    readonly header: string | null | undefined;
+    /** The webhook's signing secret, returned once by `createWebhook`. */
+    readonly secret: string;
+    /** Maximum age (or clock skew) of the signed timestamp. Defaults to 300 seconds. */
+    readonly toleranceSeconds?: number;
+    /** Current time in unix seconds, for tests. Defaults to the system clock. */
+    readonly now?: number;
+}
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * Check an `Adeli-Signature` header against the raw body. Returns false for a
+ * malformed header, a timestamp outside the tolerance, or a signature mismatch;
+ * the comparison is constant-time. Throws only for a missing secret or an
+ * invalid tolerance, which are configuration mistakes rather than bad deliveries.
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
+interface WebhookEventEnvelope {
+    /** Stable per provider event; deduplicate redeliveries on it. */
+    readonly id: string;
+    readonly createdAt: string;
+    readonly profileId: string;
+    readonly accountId: string;
+}
+interface CommentCreatedEvent extends WebhookEventEnvelope {
+    readonly type: 'comment.created';
+    readonly platform: 'instagram';
+    readonly data: {
+        readonly commentId: string;
+        readonly mediaId: string;
+        readonly parentId: string | null;
+        readonly text: string;
+        readonly from: {
+            readonly id: string | null;
+            readonly username: string | null;
+        };
+        /** True when the connected account wrote the comment itself. */
+        readonly isSelf: boolean;
+    };
+}
+interface MessagePostbackEvent extends WebhookEventEnvelope {
+    readonly type: 'message.postback';
+    readonly platform: 'instagram';
+    readonly data: {
+        /** The person's Instagram-scoped id; reply with `sendInstagramMessage({ recipient: { id: senderId } })`. */
+        readonly senderId: string;
+        readonly payload: string;
+        readonly title: string | null;
+        readonly messageId: string | null;
+    };
+}
+/** An event type (or platform) this SDK version does not know yet. `eventType` keeps the wire `type`. */
+interface UnknownWebhookEvent extends WebhookEventEnvelope {
+    readonly type: 'unknown';
+    readonly eventType: string;
+    readonly platform: string;
+    readonly data: unknown;
+}
+type WebhookEvent = CommentCreatedEvent | MessagePostbackEvent | UnknownWebhookEvent;
+type WebhookEventType = Exclude<WebhookEvent['type'], 'unknown'>;
+/**
+ * Parse a verified webhook body into a typed event. Known types are validated
+ * field by field; an unrecognised type parses as `type: 'unknown'` so new event
+ * types stay additive. Throws `MalformedResponseError` for invalid JSON, a
+ * missing envelope field, or a known event whose data does not match.
+ */
+declare function parseWebhookEvent(payload: WebhookPayload): WebhookEvent;
+
+export { type CommentCreatedEvent, type CommentIteratorOptions, type CommentIteratorQuery, type CommentsClient, type ConnectionPollingClient, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type FacebookPollingClient, type InstagramPollingClient, type MessagePostbackEvent, type PollingOptions, type PostPollingClient, type TikTokPollingClient, type UnknownWebhookEvent, type VerifyWebhookSignatureInput, type WebhookEvent, type WebhookEventType, type WebhookPayload, type YouTubePollingClient, iterateCommentPages, iterateComments, parseWebhookEvent, verifyWebhookSignature, waitForConnection, waitForFacebookPost, waitForInstagramPost, waitForTikTokPost, waitForYouTubeVideo };