naystack 1.5.8 → 1.5.10

package/dist/socials/instagram/getters.d.mts

@@ -1,9 +1,71 @@
 import { InstagramConversation, InstagramError, InstagramMedia, InstagramMessage, InstagramUser } from './types.mjs';
 
+/**
+ * Fetches an Instagram user's profile. Defaults to the authenticated user (`"me"`).
+ *
+ * @param token - Instagram access token.
+ * @param id - User id to fetch. Defaults to `"me"` (the token owner).
+ * @param fields - Optional array of field names to request. Default: `["username", "followers_count", "media_count"]`.
+ * @returns Promise of user data (typed as `T`, defaults to {@link InstagramUser}).
+ *
+ * @example
+ * ```ts
+ * import { getInstagramUser } from "naystack/socials";
+ *
+ * const user = await getInstagramUser(accessToken);
+ * console.log(user?.username, user?.followers_count);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramUser: <T = InstagramUser>(token: string, id?: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
+/**
+ * Fetches the authenticated user's recent Instagram media.
+ *
+ * @param token - Instagram access token.
+ * @param fields - Optional array of field names. Default: `["like_count", "comments_count", "permalink"]`.
+ * @param limit - Maximum number of items to return. Default: `12`.
+ * @returns Promise of `{ data: T[] }` where T defaults to {@link InstagramMedia}.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramMedia } from "naystack/socials";
+ *
+ * const media = await getInstagramMedia(accessToken, undefined, 10);
+ * for (const item of media?.data ?? []) {
+ *   console.log(item.permalink, item.like_count);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramMedia: <T = InstagramMedia>(token: string, fields?: string[], limit?: number) => Promise<({
     data: T[];
 } & InstagramError) | null>;
+/**
+ * Fetches Instagram conversations (DM threads) with pagination support.
+ *
+ * @param token - Instagram access token.
+ * @param limit - Page size. Default: `25`.
+ * @param cursor - Optional pagination cursor (from a previous `fetchMore`).
+ * @returns Promise of `{ data: InstagramConversation[], fetchMore?: () => Promise<...> }`.
+ *   Call `fetchMore()` to load the next page.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversations } from "naystack/socials";
+ *
+ * const convos = await getInstagramConversations(accessToken, 25);
+ * for (const convo of convos.data ?? []) {
+ *   console.log(convo.participants, convo.messages);
+ * }
+ * if (convos.fetchMore) {
+ *   const nextPage = await convos.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversations: (token: string, limit?: number, cursor?: string) => Promise<{
     data: {
         messages: {
@@ -19,10 +81,53 @@ declare const getInstagramConversations: (token: string, limit?: number, cursor?
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches conversations filtered by a specific Instagram user id.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The Instagram user id to filter conversations by.
+ * @returns Promise of `{ data: InstagramConversation[] }`.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationsByUser: (token: string, userID: string) => Promise<({
     data: InstagramConversation[];
 } & InstagramError) | null>;
+/**
+ * Fetches the single conversation between the authenticated user and the given user.
+ * Filters for conversations with exactly 2 participants.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The other participant's Instagram user id.
+ * @returns Promise of a single `InstagramConversation` or `undefined` if not found.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationByUser: (token: string, userID: string) => Promise<InstagramConversation | undefined>;
+/**
+ * Fetches a single Instagram conversation by id with messages and participants.
+ * Supports pagination for messages via `fetchMore`.
+ *
+ * @param token - Instagram access token.
+ * @param id - Conversation id.
+ * @param cursor - Optional pagination cursor for messages.
+ * @returns Promise of `{ messages, participants, fetchMore? }`.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversation } from "naystack/socials";
+ *
+ * const convo = await getInstagramConversation(accessToken, conversationId);
+ * for (const msg of convo.messages ?? []) {
+ *   console.log(msg.id, msg.created_time);
+ * }
+ * if (convo.fetchMore) {
+ *   const older = await convo.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversation: (token: string, id: string, cursor?: string) => Promise<{
     messages: {
         id: string;
@@ -34,6 +139,16 @@ declare const getInstagramConversation: (token: string, id: string, cursor?: str
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches a single Instagram message by id.
+ *
+ * @param token - Instagram access token.
+ * @param id - Message id.
+ * @param fields - Optional array of field names. Default: `["id", "created_time", "from", "to", "message"]`.
+ * @returns Promise of message data (typed as `T`, defaults to {@link InstagramMessage}).
+ *
+ * @category Socials
+ */
 declare const getInstagramMessage: <T = InstagramMessage>(token: string, id: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
 
 export { getInstagramConversation, getInstagramConversationByUser, getInstagramConversations, getInstagramConversationsByUser, getInstagramMedia, getInstagramMessage, getInstagramUser };

package/dist/socials/instagram/getters.d.ts

@@ -1,9 +1,71 @@
 import { InstagramConversation, InstagramError, InstagramMedia, InstagramMessage, InstagramUser } from './types.js';
 
+/**
+ * Fetches an Instagram user's profile. Defaults to the authenticated user (`"me"`).
+ *
+ * @param token - Instagram access token.
+ * @param id - User id to fetch. Defaults to `"me"` (the token owner).
+ * @param fields - Optional array of field names to request. Default: `["username", "followers_count", "media_count"]`.
+ * @returns Promise of user data (typed as `T`, defaults to {@link InstagramUser}).
+ *
+ * @example
+ * ```ts
+ * import { getInstagramUser } from "naystack/socials";
+ *
+ * const user = await getInstagramUser(accessToken);
+ * console.log(user?.username, user?.followers_count);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramUser: <T = InstagramUser>(token: string, id?: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
+/**
+ * Fetches the authenticated user's recent Instagram media.
+ *
+ * @param token - Instagram access token.
+ * @param fields - Optional array of field names. Default: `["like_count", "comments_count", "permalink"]`.
+ * @param limit - Maximum number of items to return. Default: `12`.
+ * @returns Promise of `{ data: T[] }` where T defaults to {@link InstagramMedia}.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramMedia } from "naystack/socials";
+ *
+ * const media = await getInstagramMedia(accessToken, undefined, 10);
+ * for (const item of media?.data ?? []) {
+ *   console.log(item.permalink, item.like_count);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramMedia: <T = InstagramMedia>(token: string, fields?: string[], limit?: number) => Promise<({
     data: T[];
 } & InstagramError) | null>;
+/**
+ * Fetches Instagram conversations (DM threads) with pagination support.
+ *
+ * @param token - Instagram access token.
+ * @param limit - Page size. Default: `25`.
+ * @param cursor - Optional pagination cursor (from a previous `fetchMore`).
+ * @returns Promise of `{ data: InstagramConversation[], fetchMore?: () => Promise<...> }`.
+ *   Call `fetchMore()` to load the next page.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversations } from "naystack/socials";
+ *
+ * const convos = await getInstagramConversations(accessToken, 25);
+ * for (const convo of convos.data ?? []) {
+ *   console.log(convo.participants, convo.messages);
+ * }
+ * if (convos.fetchMore) {
+ *   const nextPage = await convos.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversations: (token: string, limit?: number, cursor?: string) => Promise<{
     data: {
         messages: {
@@ -19,10 +81,53 @@ declare const getInstagramConversations: (token: string, limit?: number, cursor?
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches conversations filtered by a specific Instagram user id.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The Instagram user id to filter conversations by.
+ * @returns Promise of `{ data: InstagramConversation[] }`.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationsByUser: (token: string, userID: string) => Promise<({
     data: InstagramConversation[];
 } & InstagramError) | null>;
+/**
+ * Fetches the single conversation between the authenticated user and the given user.
+ * Filters for conversations with exactly 2 participants.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The other participant's Instagram user id.
+ * @returns Promise of a single `InstagramConversation` or `undefined` if not found.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationByUser: (token: string, userID: string) => Promise<InstagramConversation | undefined>;
+/**
+ * Fetches a single Instagram conversation by id with messages and participants.
+ * Supports pagination for messages via `fetchMore`.
+ *
+ * @param token - Instagram access token.
+ * @param id - Conversation id.
+ * @param cursor - Optional pagination cursor for messages.
+ * @returns Promise of `{ messages, participants, fetchMore? }`.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversation } from "naystack/socials";
+ *
+ * const convo = await getInstagramConversation(accessToken, conversationId);
+ * for (const msg of convo.messages ?? []) {
+ *   console.log(msg.id, msg.created_time);
+ * }
+ * if (convo.fetchMore) {
+ *   const older = await convo.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversation: (token: string, id: string, cursor?: string) => Promise<{
     messages: {
         id: string;
@@ -34,6 +139,16 @@ declare const getInstagramConversation: (token: string, id: string, cursor?: str
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches a single Instagram message by id.
+ *
+ * @param token - Instagram access token.
+ * @param id - Message id.
+ * @param fields - Optional array of field names. Default: `["id", "created_time", "from", "to", "message"]`.
+ * @returns Promise of message data (typed as `T`, defaults to {@link InstagramMessage}).
+ *
+ * @category Socials
+ */
 declare const getInstagramMessage: <T = InstagramMessage>(token: string, id: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
 
 export { getInstagramConversation, getInstagramConversationByUser, getInstagramConversations, getInstagramConversationsByUser, getInstagramMedia, getInstagramMessage, getInstagramUser };

package/dist/socials/instagram/setters.d.mts

@@ -1,5 +1,23 @@
 import { InstagramError } from './types.mjs';
 
+/**
+ * Sends a text message to an Instagram user via the Instagram Messaging API.
+ *
+ * @param token - Instagram access token.
+ * @param to - Recipient's Instagram user id.
+ * @param text - Message text to send.
+ * @returns Promise of `{ recipient_id, message_id }` on success.
+ *
+ * @example
+ * ```ts
+ * import { sendInstagramMessage } from "naystack/socials";
+ *
+ * const result = await sendInstagramMessage(accessToken, recipientId, "Hello!");
+ * console.log("Sent message:", result?.message_id);
+ * ```
+ *
+ * @category Socials
+ */
 declare const sendInstagramMessage: (token: string, to: string, text: string) => Promise<({
     recipient_id?: string;
     message_id?: string;

package/dist/socials/instagram/setters.d.ts

@@ -1,5 +1,23 @@
 import { InstagramError } from './types.js';
 
+/**
+ * Sends a text message to an Instagram user via the Instagram Messaging API.
+ *
+ * @param token - Instagram access token.
+ * @param to - Recipient's Instagram user id.
+ * @param text - Message text to send.
+ * @returns Promise of `{ recipient_id, message_id }` on success.
+ *
+ * @example
+ * ```ts
+ * import { sendInstagramMessage } from "naystack/socials";
+ *
+ * const result = await sendInstagramMessage(accessToken, recipientId, "Hello!");
+ * console.log("Sent message:", result?.message_id);
+ * ```
+ *
+ * @category Socials
+ */
 declare const sendInstagramMessage: (token: string, to: string, text: string) => Promise<({
     recipient_id?: string;
     message_id?: string;

package/dist/socials/instagram/types.d.mts

@@ -1,3 +1,14 @@
+/**
+ * Instagram Messaging API message shape.
+ *
+ * @property id - Message id.
+ * @property created_time - ISO timestamp of when the message was sent.
+ * @property from - Sender's id and username.
+ * @property to - Array of recipient ids and usernames.
+ * @property message - Text content of the message.
+ *
+ * @category Socials
+ */
 type InstagramMessage = {
     id: string;
     created_time: string;
@@ -13,16 +24,44 @@ type InstagramMessage = {
     };
     message: string;
 };
+/**
+ * Instagram user/profile data (e.g. from the `"me"` endpoint).
+ *
+ * @property username - Instagram handle.
+ * @property followers_count - Number of followers.
+ * @property media_count - Number of media posts.
+ *
+ * @category Socials
+ */
 type InstagramUser = {
     username: string;
     followers_count: number;
     media_count: number;
 };
+/**
+ * Instagram media item (e.g. from the `me/media` endpoint).
+ *
+ * @property like_count - Number of likes (may be undefined if not requested).
+ * @property comments_count - Number of comments.
+ * @property permalink - Permanent URL to the post on Instagram.
+ *
+ * @category Socials
+ */
 type InstagramMedia = {
     like_count?: number;
     comments_count: number;
     permalink: string;
 };
+/**
+ * Instagram conversation (DM thread) from the Messaging API.
+ *
+ * @property id - Conversation id.
+ * @property updated_time - ISO timestamp of the last update.
+ * @property messages - Optional nested messages with pagination cursors.
+ * @property participants - Optional array of participant ids and usernames.
+ *
+ * @category Socials
+ */
 type InstagramConversation = {
     id: string;
     updated_time: string;
@@ -44,6 +83,13 @@ type InstagramConversation = {
         }[];
     };
 };
+/**
+ * Instagram Graph API error response shape.
+ *
+ * @property error - Error details from the API (message, type, code, subcode, trace id).
+ *
+ * @category Socials
+ */
 type InstagramError = {
     error?: {
         message: string;

package/dist/socials/instagram/types.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Instagram Messaging API message shape.
+ *
+ * @property id - Message id.
+ * @property created_time - ISO timestamp of when the message was sent.
+ * @property from - Sender's id and username.
+ * @property to - Array of recipient ids and usernames.
+ * @property message - Text content of the message.
+ *
+ * @category Socials
+ */
 type InstagramMessage = {
     id: string;
     created_time: string;
@@ -13,16 +24,44 @@ type InstagramMessage = {
     };
     message: string;
 };
+/**
+ * Instagram user/profile data (e.g. from the `"me"` endpoint).
+ *
+ * @property username - Instagram handle.
+ * @property followers_count - Number of followers.
+ * @property media_count - Number of media posts.
+ *
+ * @category Socials
+ */
 type InstagramUser = {
     username: string;
     followers_count: number;
     media_count: number;
 };
+/**
+ * Instagram media item (e.g. from the `me/media` endpoint).
+ *
+ * @property like_count - Number of likes (may be undefined if not requested).
+ * @property comments_count - Number of comments.
+ * @property permalink - Permanent URL to the post on Instagram.
+ *
+ * @category Socials
+ */
 type InstagramMedia = {
     like_count?: number;
     comments_count: number;
     permalink: string;
 };
+/**
+ * Instagram conversation (DM thread) from the Messaging API.
+ *
+ * @property id - Conversation id.
+ * @property updated_time - ISO timestamp of the last update.
+ * @property messages - Optional nested messages with pagination cursors.
+ * @property participants - Optional array of participant ids and usernames.
+ *
+ * @category Socials
+ */
 type InstagramConversation = {
     id: string;
     updated_time: string;
@@ -44,6 +83,13 @@ type InstagramConversation = {
         }[];
     };
 };
+/**
+ * Instagram Graph API error response shape.
+ *
+ * @property error - Error details from the API (message, type, code, subcode, trace id).
+ *
+ * @category Socials
+ */
 type InstagramError = {
     error?: {
         message: string;

package/dist/socials/instagram/utils.d.mts

@@ -1,6 +1,25 @@
 import { InstagramError } from './types.mjs';
 
+/**
+ * Builds an Instagram Graph API URL with the given path and query parameters (includes `access_token`).
+ *
+ * @param token - Instagram access token.
+ * @param path - API path (e.g. `"me"`, `"me/media"`, `"me/conversations"`).
+ * @param params - Additional query parameters.
+ * @returns Full URL string.
+ * @category Socials
+ */
 declare function getInstagramURL(token: string, path: string, params: Record<string, string>): string;
+/**
+ * Fetches JSON from the Instagram Graph API (GET or POST depending on whether `postData` is provided).
+ *
+ * @param token - Instagram access token.
+ * @param path - API path.
+ * @param params - Query parameters (default: `{}`).
+ * @param postData - Optional POST body (if provided, the request becomes a POST).
+ * @returns Promise of `(T & InstagramError) | null`.
+ * @category Socials
+ */
 declare function getInstagramData<T>(token: string, path: string, params?: Record<string, string>, postData?: object): Promise<(T & InstagramError) | null>;
 
 export { getInstagramData, getInstagramURL };

package/dist/socials/instagram/utils.d.ts

@@ -1,6 +1,25 @@
 import { InstagramError } from './types.js';
 
+/**
+ * Builds an Instagram Graph API URL with the given path and query parameters (includes `access_token`).
+ *
+ * @param token - Instagram access token.
+ * @param path - API path (e.g. `"me"`, `"me/media"`, `"me/conversations"`).
+ * @param params - Additional query parameters.
+ * @returns Full URL string.
+ * @category Socials
+ */
 declare function getInstagramURL(token: string, path: string, params: Record<string, string>): string;
+/**
+ * Fetches JSON from the Instagram Graph API (GET or POST depending on whether `postData` is provided).
+ *
+ * @param token - Instagram access token.
+ * @param path - API path.
+ * @param params - Query parameters (default: `{}`).
+ * @param postData - Optional POST body (if provided, the request becomes a POST).
+ * @returns Promise of `(T & InstagramError) | null`.
+ * @category Socials
+ */
 declare function getInstagramData<T>(token: string, path: string, params?: Record<string, string>, postData?: object): Promise<(T & InstagramError) | null>;
 
 export { getInstagramData, getInstagramURL };

package/dist/socials/instagram/webhook.d.mts

@@ -1,6 +1,37 @@
 import * as next_server from 'next/server';
 import { NextRequest } from 'next/server';
 
+/**
+ * Sets up GET (verification) and POST (event handling) route handlers for the Instagram webhook.
+ *
+ * - **GET**: Responds to Meta's webhook verification challenge (checks `hub.verify_token` against `secret`).
+ * - **POST**: Parses incoming webhook events and calls your `callback` for each event in the payload.
+ *
+ * @param options - Configuration object.
+ * @param options.secret - The verify token you configured in the Meta Developer Portal.
+ * @param options.callback - Called for each webhook event: `(type, value, pageId) => Promise<void>`.
+ *   - `type` — Event type (e.g. `"messaging"`, `"changes"`).
+ *   - `value` — Event payload.
+ *   - `id` — The page/account id from the entry.
+ * @returns Object with `GET` and `POST` — export as your route's handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/instagram/route.ts
+ * import { setupInstagramWebhook } from "naystack/socials";
+ *
+ * export const { GET, POST } = setupInstagramWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   callback: async (type, value, id) => {
+ *     if (type === "messaging") {
+ *       console.log("New message from page", id, value);
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @category Socials
+ */
 declare const setupInstagramWebhook: (options: {
     secret: string;
     callback: (type: string, value: any, id: string) => Promise<void>;

package/dist/socials/instagram/webhook.d.ts

@@ -1,6 +1,37 @@
 import * as next_server from 'next/server';
 import { NextRequest } from 'next/server';
 
+/**
+ * Sets up GET (verification) and POST (event handling) route handlers for the Instagram webhook.
+ *
+ * - **GET**: Responds to Meta's webhook verification challenge (checks `hub.verify_token` against `secret`).
+ * - **POST**: Parses incoming webhook events and calls your `callback` for each event in the payload.
+ *
+ * @param options - Configuration object.
+ * @param options.secret - The verify token you configured in the Meta Developer Portal.
+ * @param options.callback - Called for each webhook event: `(type, value, pageId) => Promise<void>`.
+ *   - `type` — Event type (e.g. `"messaging"`, `"changes"`).
+ *   - `value` — Event payload.
+ *   - `id` — The page/account id from the entry.
+ * @returns Object with `GET` and `POST` — export as your route's handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/instagram/route.ts
+ * import { setupInstagramWebhook } from "naystack/socials";
+ *
+ * export const { GET, POST } = setupInstagramWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   callback: async (type, value, id) => {
+ *     if (type === "messaging") {
+ *       console.log("New message from page", id, value);
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @category Socials
+ */
 declare const setupInstagramWebhook: (options: {
     secret: string;
     callback: (type: string, value: any, id: string) => Promise<void>;

package/dist/socials/meta-webhook.d.mts

@@ -1,5 +1,16 @@
 import { NextRequest, NextResponse } from 'next/server';
 
+/**
+ * Returns a GET handler that verifies a Meta (Instagram/Threads) webhook subscription.
+ * Responds with `hub.challenge` when `hub.verify_token` matches the provided secret.
+ *
+ * Used internally by `setupInstagramWebhook` and `setupThreadsWebhook`.
+ *
+ * @param secret - Expected `hub.verify_token` value (configured in the Meta Developer Portal).
+ * @returns GET route handler that responds to Meta's verification request.
+ *
+ * @category Socials
+ */
 declare const verifyWebhook: (secret: string) => (req: NextRequest) => NextResponse<unknown> | undefined;
 
 export { verifyWebhook };

package/dist/socials/meta-webhook.d.ts

@@ -1,5 +1,16 @@
 import { NextRequest, NextResponse } from 'next/server';
 
+/**
+ * Returns a GET handler that verifies a Meta (Instagram/Threads) webhook subscription.
+ * Responds with `hub.challenge` when `hub.verify_token` matches the provided secret.
+ *
+ * Used internally by `setupInstagramWebhook` and `setupThreadsWebhook`.
+ *
+ * @param secret - Expected `hub.verify_token` value (configured in the Meta Developer Portal).
+ * @returns GET route handler that responds to Meta's verification request.
+ *
+ * @category Socials
+ */
 declare const verifyWebhook: (secret: string) => (req: NextRequest) => NextResponse<unknown> | undefined;
 
 export { verifyWebhook };