naystack 1.5.9 → 1.5.11

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 };

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

@@ -1,7 +1,64 @@
 import { ThreadsPost } from './types.mjs';
 
+/**
+ * Fetches a single Threads post by id.
+ *
+ * @param token - Threads access token.
+ * @param id - Post id.
+ * @param fields - Optional array of field names. Default: `["text", "permalink", "username"]`.
+ * @returns Promise of post data (typed as `T`, defaults to {@link ThreadsPost}).
+ *
+ * @example
+ * ```ts
+ * import { getThread } from "naystack/socials";
+ *
+ * const post = await getThread(accessToken, postId);
+ * console.log(post?.text, post?.permalink);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T | null>;
+/**
+ * Fetches the authenticated user's Threads posts.
+ *
+ * @param token - Threads access token.
+ * @param fields - Optional array of field names. Default: `["text", "permalink", "username"]`.
+ * @returns Promise of an array of posts (typed as `T[]`, defaults to {@link ThreadsPost}`[]`).
+ *
+ * @example
+ * ```ts
+ * import { getThreads } from "naystack/socials";
+ *
+ * const threads = await getThreads(accessToken);
+ * for (const thread of threads ?? []) {
+ *   console.log(thread.text, thread.permalink);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThreads: <T = ThreadsPost>(token: string, fields?: string[]) => Promise<T[] | undefined>;
+/**
+ * Fetches replies to a Threads post.
+ *
+ * @param token - Threads access token.
+ * @param id - Parent post id.
+ * @param fields - Optional array of field names. Default: `["text", "username", "permalink"]`.
+ * @returns Promise of an array of reply posts.
+ *
+ * @example
+ * ```ts
+ * import { getThreadsReplies } from "naystack/socials";
+ *
+ * const replies = await getThreadsReplies(accessToken, postId);
+ * for (const reply of replies ?? []) {
+ *   console.log(reply.username, ":", reply.text);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThreadsReplies: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T[] | undefined>;
 
 export { getThread, getThreads, getThreadsReplies };

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

@@ -1,7 +1,64 @@
 import { ThreadsPost } from './types.js';
 
+/**
+ * Fetches a single Threads post by id.
+ *
+ * @param token - Threads access token.
+ * @param id - Post id.
+ * @param fields - Optional array of field names. Default: `["text", "permalink", "username"]`.
+ * @returns Promise of post data (typed as `T`, defaults to {@link ThreadsPost}).
+ *
+ * @example
+ * ```ts
+ * import { getThread } from "naystack/socials";
+ *
+ * const post = await getThread(accessToken, postId);
+ * console.log(post?.text, post?.permalink);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T | null>;
+/**
+ * Fetches the authenticated user's Threads posts.
+ *
+ * @param token - Threads access token.
+ * @param fields - Optional array of field names. Default: `["text", "permalink", "username"]`.
+ * @returns Promise of an array of posts (typed as `T[]`, defaults to {@link ThreadsPost}`[]`).
+ *
+ * @example
+ * ```ts
+ * import { getThreads } from "naystack/socials";
+ *
+ * const threads = await getThreads(accessToken);
+ * for (const thread of threads ?? []) {
+ *   console.log(thread.text, thread.permalink);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThreads: <T = ThreadsPost>(token: string, fields?: string[]) => Promise<T[] | undefined>;
+/**
+ * Fetches replies to a Threads post.
+ *
+ * @param token - Threads access token.
+ * @param id - Parent post id.
+ * @param fields - Optional array of field names. Default: `["text", "username", "permalink"]`.
+ * @returns Promise of an array of reply posts.
+ *
+ * @example
+ * ```ts
+ * import { getThreadsReplies } from "naystack/socials";
+ *
+ * const replies = await getThreadsReplies(accessToken, postId);
+ * for (const reply of replies ?? []) {
+ *   console.log(reply.username, ":", reply.text);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getThreadsReplies: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T[] | undefined>;
 
 export { getThread, getThreads, getThreadsReplies };

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

@@ -1,6 +1,65 @@
+/**
+ * Creates a Threads container (draft post). Must be published with `publishContainer`.
+ * This is a low-level function — prefer using {@link createThreadsPost} which handles both steps.
+ *
+ * @param token - Threads access token.
+ * @param text - Post text.
+ * @param reply_to_id - Optional parent post id (for replies).
+ * @returns Promise of the container creation id.
+ * @category Socials
+ */
 declare function createContainer(token: string, text: string, reply_to_id?: string): Promise<string | undefined>;
+/**
+ * Publishes a Threads container (created with `createContainer`).
+ * This is a low-level function — prefer using {@link createThreadsPost} which handles both steps.
+ *
+ * @param token - Threads access token.
+ * @param creation_id - Container id from `createContainer`.
+ * @returns Promise of the published post id.
+ * @category Socials
+ */
 declare function publishContainer(token: string, creation_id: string): Promise<string | undefined>;
+/**
+ * Creates and publishes a single Threads post. Handles the two-step container + publish flow
+ * with an automatic 2-second delay between creation and publishing (required by the Threads API).
+ *
+ * @param token - Threads access token.
+ * @param text - Post text.
+ * @param reply_to_id - Optional parent post id (to make this post a reply).
+ * @returns Promise of the published post id, or `null` if creation failed.
+ *
+ * @example
+ * ```ts
+ * import { createThreadsPost } from "naystack/socials";
+ *
+ * const postId = await createThreadsPost(accessToken, "Hello from Naystack!");
+ * console.log("Published:", postId);
+ * ```
+ *
+ * @category Socials
+ */
 declare const createThreadsPost: (token: string, text: string, reply_to_id?: string) => Promise<string | null | undefined>;
+/**
+ * Creates a thread — a sequence of posts where each replies to the previous one.
+ * Newlines in post text are converted to `%0A` for the API.
+ *
+ * @param token - Threads access token.
+ * @param threads - Array of post text strings (in order). Each post after the first becomes a reply to the previous.
+ * @returns Promise of the first published post's id.
+ *
+ * @example
+ * ```ts
+ * import { createThread } from "naystack/socials";
+ *
+ * const firstPostId = await createThread(accessToken, [
+ *   "First post in thread",
+ *   "Second post (reply to first)",
+ *   "Third post (reply to second)",
+ * ]);
+ * ```
+ *
+ * @category Socials
+ */
 declare const createThread: (token: string, threads: string[]) => Promise<string | undefined>;
 
 export { createContainer, createThread, createThreadsPost, publishContainer };

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

@@ -1,6 +1,65 @@
+/**
+ * Creates a Threads container (draft post). Must be published with `publishContainer`.
+ * This is a low-level function — prefer using {@link createThreadsPost} which handles both steps.
+ *
+ * @param token - Threads access token.
+ * @param text - Post text.
+ * @param reply_to_id - Optional parent post id (for replies).
+ * @returns Promise of the container creation id.
+ * @category Socials
+ */
 declare function createContainer(token: string, text: string, reply_to_id?: string): Promise<string | undefined>;
+/**
+ * Publishes a Threads container (created with `createContainer`).
+ * This is a low-level function — prefer using {@link createThreadsPost} which handles both steps.
+ *
+ * @param token - Threads access token.
+ * @param creation_id - Container id from `createContainer`.
+ * @returns Promise of the published post id.
+ * @category Socials
+ */
 declare function publishContainer(token: string, creation_id: string): Promise<string | undefined>;
+/**
+ * Creates and publishes a single Threads post. Handles the two-step container + publish flow
+ * with an automatic 2-second delay between creation and publishing (required by the Threads API).
+ *
+ * @param token - Threads access token.
+ * @param text - Post text.
+ * @param reply_to_id - Optional parent post id (to make this post a reply).
+ * @returns Promise of the published post id, or `null` if creation failed.
+ *
+ * @example
+ * ```ts
+ * import { createThreadsPost } from "naystack/socials";
+ *
+ * const postId = await createThreadsPost(accessToken, "Hello from Naystack!");
+ * console.log("Published:", postId);
+ * ```
+ *
+ * @category Socials
+ */
 declare const createThreadsPost: (token: string, text: string, reply_to_id?: string) => Promise<string | null | undefined>;
+/**
+ * Creates a thread — a sequence of posts where each replies to the previous one.
+ * Newlines in post text are converted to `%0A` for the API.
+ *
+ * @param token - Threads access token.
+ * @param threads - Array of post text strings (in order). Each post after the first becomes a reply to the previous.
+ * @returns Promise of the first published post's id.
+ *
+ * @example
+ * ```ts
+ * import { createThread } from "naystack/socials";
+ *
+ * const firstPostId = await createThread(accessToken, [
+ *   "First post in thread",
+ *   "Second post (reply to first)",
+ *   "Third post (reply to second)",
+ * ]);
+ * ```
+ *
+ * @category Socials
+ */
 declare const createThread: (token: string, threads: string[]) => Promise<string | undefined>;
 
 export { createContainer, createThread, createThreadsPost, publishContainer };

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

@@ -1,3 +1,12 @@
+/**
+ * Threads post (single post or reply).
+ *
+ * @property text - Post text content.
+ * @property permalink - Permanent URL to the post on Threads.
+ * @property username - Author's username.
+ *
+ * @category Socials
+ */
 type ThreadsPost = {
     text: string;
     permalink: string;

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

@@ -1,3 +1,12 @@
+/**
+ * Threads post (single post or reply).
+ *
+ * @property text - Post text content.
+ * @property permalink - Permanent URL to the post on Threads.
+ * @property username - Author's username.
+ *
+ * @category Socials
+ */
 type ThreadsPost = {
     text: string;
     permalink: string;

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

@@ -1,4 +1,23 @@
+/**
+ * Builds a Threads Graph API URL with the given path and query parameters (includes `access_token`).
+ *
+ * @param token - Threads access token.
+ * @param path - API path (e.g. `"me/threads"`, `"me/threads_publish"`).
+ * @param params - Query parameters.
+ * @returns Full URL string.
+ * @category Socials
+ */
 declare function getThreadsURL(token: string, path: string, params: Record<string, string>): string;
+/**
+ * Fetches JSON from the Threads Graph API (GET or POST).
+ *
+ * @param token - Threads access token.
+ * @param path - API path.
+ * @param params - Query parameters.
+ * @param method - Set to `"POST"` for mutations; defaults to `"GET"`.
+ * @returns Promise of response data (typed as `T`) or `null`.
+ * @category Socials
+ */
 declare function getThreadsData<T>(token: string, path: string, params: Record<string, string>, method?: "POST"): Promise<T | null>;
 
 export { getThreadsData, getThreadsURL };

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

@@ -1,4 +1,23 @@
+/**
+ * Builds a Threads Graph API URL with the given path and query parameters (includes `access_token`).
+ *
+ * @param token - Threads access token.
+ * @param path - API path (e.g. `"me/threads"`, `"me/threads_publish"`).
+ * @param params - Query parameters.
+ * @returns Full URL string.
+ * @category Socials
+ */
 declare function getThreadsURL(token: string, path: string, params: Record<string, string>): string;
+/**
+ * Fetches JSON from the Threads Graph API (GET or POST).
+ *
+ * @param token - Threads access token.
+ * @param path - API path.
+ * @param params - Query parameters.
+ * @param method - Set to `"POST"` for mutations; defaults to `"GET"`.
+ * @returns Promise of response data (typed as `T`) or `null`.
+ * @category Socials
+ */
 declare function getThreadsData<T>(token: string, path: string, params: Record<string, string>, method?: "POST"): Promise<T | null>;
 
 export { getThreadsData, getThreadsURL };