naystack 1.5.8 → 1.5.10

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

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

@@ -1,6 +1,36 @@
 import * as next_server from 'next/server';
 import { NextRequest } from 'next/server';
 
+/**
+ * Sets up GET (verification) and POST (event handling) route handlers for the Threads 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.
+ *
+ * @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: `(field, value) => Promise<boolean>`.
+ *   - `field` — Event field name.
+ *   - `value` — Event payload.
+ *   Return `true` to acknowledge; return `false` to respond with HTTP 500.
+ * @returns Object with `GET` and `POST` — export as your route's handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/threads/route.ts
+ * import { setupThreadsWebhook } from "naystack/socials";
+ *
+ * export const { GET, POST } = setupThreadsWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   callback: async (field, value) => {
+ *     console.log("Threads event:", field, value);
+ *     return true; // Return false to respond with 500
+ *   },
+ * });
+ * ```
+ *
+ * @category Socials
+ */
 declare const setupThreadsWebhook: (options: {
     secret: string;
     callback: (type: string, value: any) => Promise<boolean>;

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

@@ -1,6 +1,36 @@
 import * as next_server from 'next/server';
 import { NextRequest } from 'next/server';
 
+/**
+ * Sets up GET (verification) and POST (event handling) route handlers for the Threads 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.
+ *
+ * @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: `(field, value) => Promise<boolean>`.
+ *   - `field` — Event field name.
+ *   - `value` — Event payload.
+ *   Return `true` to acknowledge; return `false` to respond with HTTP 500.
+ * @returns Object with `GET` and `POST` — export as your route's handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/threads/route.ts
+ * import { setupThreadsWebhook } from "naystack/socials";
+ *
+ * export const { GET, POST } = setupThreadsWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   callback: async (field, value) => {
+ *     console.log("Threads event:", field, value);
+ *     return true; // Return false to respond with 500
+ *   },
+ * });
+ * ```
+ *
+ * @category Socials
+ */
 declare const setupThreadsWebhook: (options: {
     secret: string;
     callback: (type: string, value: any) => Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naystack",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "A stack built with Next + GraphQL + S3 + Auth",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -9,7 +9,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "NODE_OPTIONS='--max-old-space-size=16384' tsup"
+    "build": "NODE_OPTIONS='--max-old-space-size=16384' tsup",
+    "docs": "typedoc"
   },
   "exports": {
     "./auth": {
@@ -125,6 +126,7 @@
     "prettier": "^3.5.3",
     "tsup": "^8.5.0",
     "tsx": "^4.20.5",
+    "typedoc": "^0.28.16",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.31.1"
   },