naystack 1.8.12 → 1.8.14

package/dist/socials/threads/getters.esm.js

@@ -1,31 +1,55 @@
-// src/socials/threads/utils.ts
-function getThreadsURL(token, path, params) {
-  return `https://graph.threads.net/v1.0/${path}?${Object.keys(params).map((key) => `${key}=${params[key]}`).join("&")}&access_token=${token}`;
-}
-function getThreadsData(token, path, params, method) {
-  return fetch(getThreadsURL(token, path, params), {
-    method: method || "GET"
-  }).then((res) => res.json());
+// src/socials/meta/request.ts
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
 }
 
+// src/socials/threads/utils.ts
+var client = createGraphClient("https://graph.threads.net/v1.0");
+var getThreadsData = client.request;
+
 // src/socials/threads/getters.ts
 var getThread = (token, id, fields) => {
   return getThreadsData(token, id, {
-    fields: fields ? fields.join(",") : "text,permalink,username"
+    params: { fields: fields ? fields.join(",") : "text,permalink,username" }
   });
 };
 var getThreads = (token, fields) => {
   return getThreadsData(token, "me/threads", {
-    fields: fields ? fields.join(",") : "text,permalink,username"
+    params: { fields: fields ? fields.join(",") : "text,permalink,username" }
   }).then((res) => res?.data);
 };
 var getThreadsReplies = (token, id, fields) => {
   return getThreadsData(token, `${id}/replies`, {
-    fields: fields ? fields.join(",") : "text,username,permalink"
+    params: { fields: fields ? fields.join(",") : "text,username,permalink" }
   }).then((res) => res?.data);
 };
+var getThreadsContainerStatus = async (token, id) => {
+  const result = await getThreadsData(token, id, { params: { fields: "status,error_message" } });
+  if (!result?.status) return null;
+  return { status: result.status, error: result.error_message };
+};
 export {
   getThread,
   getThreads,
+  getThreadsContainerStatus,
   getThreadsReplies
 };

package/dist/socials/threads/setters.cjs.js

@@ -20,68 +20,174 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/socials/threads/setters.ts
 var setters_exports = {};
 __export(setters_exports, {
-  createContainer: () => createContainer,
   createThread: () => createThread,
-  createThreadsPost: () => createThreadsPost,
-  publishContainer: () => publishContainer
+  createThreadsPost: () => createThreadsPost
 });
 module.exports = __toCommonJS(setters_exports);
 
-// src/socials/threads/utils.ts
-function getThreadsURL(token, path, params) {
-  return `https://graph.threads.net/v1.0/${path}?${Object.keys(params).map((key) => `${key}=${params[key]}`).join("&")}&access_token=${token}`;
+// src/socials/meta/container.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForContainer(getState, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+  const deadline = Date.now() + timeoutMS;
+  let state = await getState();
+  if (!state) {
+    await sleep(2e3);
+    return null;
+  }
+  while (state?.status === "IN_PROGRESS" && Date.now() < deadline) {
+    await sleep(intervalMS);
+    state = await getState();
+  }
+  return state;
 }
-function getThreadsData(token, path, params, method) {
-  return fetch(getThreadsURL(token, path, params), {
-    method: method || "GET"
-  }).then((res) => res.json());
+function createPublisher(platform) {
+  const isReady = async (token, id, label, wait) => {
+    const state = await waitForContainer(
+      () => platform.getStatus(token, id),
+      wait
+    );
+    if (state && state.status !== "FINISHED" && state.status !== "PUBLISHED") {
+      console.error(
+        `[naystack] ${platform.name} ${label} ${id} is ${state.status}${state.error ? `: ${state.error}` : ""}`
+      );
+      return false;
+    }
+    return true;
+  };
+  return {
+    /** Creates a container, waits for it to finish processing, then publishes it. */
+    publish: async (token, params, wait) => {
+      const containerID = await platform.createContainer(token, params);
+      if (!containerID) return null;
+      if (!await isReady(token, containerID, "container", wait)) return null;
+      return platform.publish(token, containerID);
+    },
+    /** Creates and awaits every carousel child, resolving to their ids — or `null` if any failed. */
+    createChildren: async (token, items, wait) => {
+      const children = [];
+      for (const item of items) {
+        const childID = await platform.createContainer(token, {
+          ...item,
+          is_carousel_item: true
+        });
+        if (!childID) return null;
+        if (!await isReady(token, childID, "carousel item", wait))
+          return null;
+        children.push(childID);
+      }
+      return children;
+    }
+  };
 }
 
-// src/socials/threads/setters.ts
-function createContainer(token, text, reply_to_id) {
-  return getThreadsData(
-    token,
-    "me/threads",
-    {
-      media_type: "TEXT",
-      text,
-      ...reply_to_id ? { reply_to_id } : {}
-    },
-    "POST"
-  ).then((res) => res?.id);
+// src/socials/meta/request.ts
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
+}
+function readGraphID(label, result) {
+  if (result?.error) {
+    console.error(`[naystack] ${label} failed: ${result.error.message}`);
+    return null;
+  }
+  return result?.id || null;
 }
-function publishContainer(token, creation_id) {
-  return getThreadsData(
+
+// src/socials/threads/utils.ts
+var client = createGraphClient("https://graph.threads.net/v1.0");
+var getThreadsData = client.request;
+
+// src/socials/threads/getters.ts
+var getThreadsContainerStatus = async (token, id) => {
+  const result = await getThreadsData(token, id, { params: { fields: "status,error_message" } });
+  if (!result?.status) return null;
+  return { status: result.status, error: result.error_message };
+};
+
+// src/socials/threads/setters.ts
+var publisher = createPublisher({
+  name: "Threads",
+  getStatus: getThreadsContainerStatus,
+  createContainer: async (token, params) => readGraphID(
+    "Threads container",
+    await getThreadsData(token, "me/threads", {
+      params,
+      method: "POST"
+    })
+  ),
+  publish: async (token, creationID) => readGraphID(
+    "Threads publish",
+    await getThreadsData(token, "me/threads_publish", {
+      params: { creation_id: creationID },
+      method: "POST"
+    })
+  )
+});
+var mediaParams = (media) => ({
+  media_type: media ? media.type === "video" /* Video */ ? "VIDEO" : "IMAGE" : "TEXT",
+  image_url: media?.type === "photo" /* Photo */ ? media.url : void 0,
+  video_url: media?.type === "video" /* Video */ ? media.url : void 0,
+  alt_text: media?.altText
+});
+var createThreadsPost = async (token, input, replyToID) => {
+  const post = typeof input === "string" ? { text: input } : input;
+  const media = post.media ? [post.media].flat() : [];
+  const shared = {
+    text: post.text,
+    reply_to_id: post.replyToID || replyToID,
+    reply_control: post.replyControl
+  };
+  if (media.length > 1) {
+    const children = await publisher.createChildren(
+      token,
+      media.map((item) => mediaParams(item)),
+      post.wait
+    );
+    if (!children) return null;
+    return publisher.publish(
+      token,
+      { ...shared, media_type: "CAROUSEL", children: children.join(",") },
+      post.wait
+    );
+  }
+  return publisher.publish(
     token,
-    "me/threads_publish",
     {
-      creation_id
+      ...mediaParams(media[0]),
+      ...shared,
+      link_attachment: post.linkAttachment
     },
-    "POST"
-  ).then((res) => res?.id);
-}
-var createThreadsPost = async (token, text, reply_to_id) => {
-  const containerID = await createContainer(token, text, reply_to_id);
-  if (!containerID) return null;
-  await new Promise((resolve) => setTimeout(resolve, 2e3));
-  return publishContainer(token, containerID);
+    post.wait
+  );
 };
-var createThread = async (token, threads) => {
+var createThread = async (token, posts) => {
   const publishedIDs = [];
-  for (const thread of threads) {
-    const postID = await createThreadsPost(
-      token,
-      thread.split("\n").join("%0A"),
-      publishedIDs.at(-1)
-    );
+  for (const post of posts) {
+    const postID = await createThreadsPost(token, post, publishedIDs.at(-1));
     if (postID) publishedIDs.push(postID);
   }
   return publishedIDs[0];
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createContainer,
   createThread,
-  createThreadsPost,
-  publishContainer
+  createThreadsPost
 });

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

@@ -1,50 +1,41 @@
+import { ThreadsPostInput } from './types.mjs';
+import '../meta/container.mjs';
+import '../meta/types.mjs';
+
 /**
- * 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.
+ * Publishes to Threads — text, image, video or carousel, chosen from the media you
+ * pass. Creates the container, waits for Threads to finish processing it, then publishes.
  *
- * @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.
+ * Media URLs must be publicly reachable — Threads downloads them server-side.
  *
  * @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.
+ * @param input - Post text, or a {@link ThreadsPostInput} for media, replies and reply controls.
+ * @param replyToID - Parent post id, to make this post a reply. Also settable on `input`.
+ * @returns Promise of the published post id, or `null` if any step failed (the API's error is logged).
  *
  * @example
  * ```ts
  * import { createThreadsPost } from "naystack/socials";
  *
- * const postId = await createThreadsPost(accessToken, "Hello from Naystack!");
- * console.log("Published:", postId);
+ * await createThreadsPost(accessToken, "Hello from Naystack!");
+ *
+ * await createThreadsPost(accessToken, {
+ *   text: "Campaign recap",
+ *   media: [
+ *     { url: "https://cdn.example.com/1.jpg", type: "image" },
+ *     { url: "https://cdn.example.com/2.mp4", type: "video" },
+ *   ],
+ * });
  * ```
  *
  * @category Socials
  */
-declare const createThreadsPost: (token: string, text: string, reply_to_id?: string) => Promise<string | null | undefined>;
+declare const createThreadsPost: (token: string, input: string | ThreadsPostInput, replyToID?: string) => Promise<string | null>;
 /**
- * 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.
+ * Publishes a thread — a sequence of posts where each replies to the previous one.
  *
  * @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.
+ * @param posts - Posts in order, as text or {@link ThreadsPostInput}.
  * @returns Promise of the first published post's id.
  *
  * @example
@@ -54,12 +45,12 @@ declare const createThreadsPost: (token: string, text: string, reply_to_id?: str
  * const firstPostId = await createThread(accessToken, [
  *   "First post in thread",
  *   "Second post (reply to first)",
- *   "Third post (reply to second)",
+ *   { text: "Third, with a picture", media: { url: "https://cdn.example.com/3.jpg", type: "image" } },
  * ]);
  * ```
  *
  * @category Socials
  */
-declare const createThread: (token: string, threads: string[]) => Promise<string | undefined>;
+declare const createThread: (token: string, posts: (string | ThreadsPostInput)[]) => Promise<string | undefined>;
 
-export { createContainer, createThread, createThreadsPost, publishContainer };
+export { createThread, createThreadsPost };

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

@@ -1,50 +1,41 @@
+import { ThreadsPostInput } from './types.js';
+import '../meta/container.js';
+import '../meta/types.js';
+
 /**
- * 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.
+ * Publishes to Threads — text, image, video or carousel, chosen from the media you
+ * pass. Creates the container, waits for Threads to finish processing it, then publishes.
  *
- * @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.
+ * Media URLs must be publicly reachable — Threads downloads them server-side.
  *
  * @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.
+ * @param input - Post text, or a {@link ThreadsPostInput} for media, replies and reply controls.
+ * @param replyToID - Parent post id, to make this post a reply. Also settable on `input`.
+ * @returns Promise of the published post id, or `null` if any step failed (the API's error is logged).
  *
  * @example
  * ```ts
  * import { createThreadsPost } from "naystack/socials";
  *
- * const postId = await createThreadsPost(accessToken, "Hello from Naystack!");
- * console.log("Published:", postId);
+ * await createThreadsPost(accessToken, "Hello from Naystack!");
+ *
+ * await createThreadsPost(accessToken, {
+ *   text: "Campaign recap",
+ *   media: [
+ *     { url: "https://cdn.example.com/1.jpg", type: "image" },
+ *     { url: "https://cdn.example.com/2.mp4", type: "video" },
+ *   ],
+ * });
  * ```
  *
  * @category Socials
  */
-declare const createThreadsPost: (token: string, text: string, reply_to_id?: string) => Promise<string | null | undefined>;
+declare const createThreadsPost: (token: string, input: string | ThreadsPostInput, replyToID?: string) => Promise<string | null>;
 /**
- * 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.
+ * Publishes a thread — a sequence of posts where each replies to the previous one.
  *
  * @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.
+ * @param posts - Posts in order, as text or {@link ThreadsPostInput}.
  * @returns Promise of the first published post's id.
  *
  * @example
@@ -54,12 +45,12 @@ declare const createThreadsPost: (token: string, text: string, reply_to_id?: str
  * const firstPostId = await createThread(accessToken, [
  *   "First post in thread",
  *   "Second post (reply to first)",
- *   "Third post (reply to second)",
+ *   { text: "Third, with a picture", media: { url: "https://cdn.example.com/3.jpg", type: "image" } },
  * ]);
  * ```
  *
  * @category Socials
  */
-declare const createThread: (token: string, threads: string[]) => Promise<string | undefined>;
+declare const createThread: (token: string, posts: (string | ThreadsPostInput)[]) => Promise<string | undefined>;
 
-export { createContainer, createThread, createThreadsPost, publishContainer };
+export { createThread, createThreadsPost };

package/dist/socials/threads/setters.esm.js

@@ -1,57 +1,165 @@
-// src/socials/threads/utils.ts
-function getThreadsURL(token, path, params) {
-  return `https://graph.threads.net/v1.0/${path}?${Object.keys(params).map((key) => `${key}=${params[key]}`).join("&")}&access_token=${token}`;
+// src/socials/meta/container.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForContainer(getState, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+  const deadline = Date.now() + timeoutMS;
+  let state = await getState();
+  if (!state) {
+    await sleep(2e3);
+    return null;
+  }
+  while (state?.status === "IN_PROGRESS" && Date.now() < deadline) {
+    await sleep(intervalMS);
+    state = await getState();
+  }
+  return state;
 }
-function getThreadsData(token, path, params, method) {
-  return fetch(getThreadsURL(token, path, params), {
-    method: method || "GET"
-  }).then((res) => res.json());
+function createPublisher(platform) {
+  const isReady = async (token, id, label, wait) => {
+    const state = await waitForContainer(
+      () => platform.getStatus(token, id),
+      wait
+    );
+    if (state && state.status !== "FINISHED" && state.status !== "PUBLISHED") {
+      console.error(
+        `[naystack] ${platform.name} ${label} ${id} is ${state.status}${state.error ? `: ${state.error}` : ""}`
+      );
+      return false;
+    }
+    return true;
+  };
+  return {
+    /** Creates a container, waits for it to finish processing, then publishes it. */
+    publish: async (token, params, wait) => {
+      const containerID = await platform.createContainer(token, params);
+      if (!containerID) return null;
+      if (!await isReady(token, containerID, "container", wait)) return null;
+      return platform.publish(token, containerID);
+    },
+    /** Creates and awaits every carousel child, resolving to their ids — or `null` if any failed. */
+    createChildren: async (token, items, wait) => {
+      const children = [];
+      for (const item of items) {
+        const childID = await platform.createContainer(token, {
+          ...item,
+          is_carousel_item: true
+        });
+        if (!childID) return null;
+        if (!await isReady(token, childID, "carousel item", wait))
+          return null;
+        children.push(childID);
+      }
+      return children;
+    }
+  };
 }
 
-// src/socials/threads/setters.ts
-function createContainer(token, text, reply_to_id) {
-  return getThreadsData(
-    token,
-    "me/threads",
-    {
-      media_type: "TEXT",
-      text,
-      ...reply_to_id ? { reply_to_id } : {}
-    },
-    "POST"
-  ).then((res) => res?.id);
+// src/socials/meta/request.ts
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
+}
+function readGraphID(label, result) {
+  if (result?.error) {
+    console.error(`[naystack] ${label} failed: ${result.error.message}`);
+    return null;
+  }
+  return result?.id || null;
 }
-function publishContainer(token, creation_id) {
-  return getThreadsData(
+
+// src/socials/threads/utils.ts
+var client = createGraphClient("https://graph.threads.net/v1.0");
+var getThreadsData = client.request;
+
+// src/socials/threads/getters.ts
+var getThreadsContainerStatus = async (token, id) => {
+  const result = await getThreadsData(token, id, { params: { fields: "status,error_message" } });
+  if (!result?.status) return null;
+  return { status: result.status, error: result.error_message };
+};
+
+// src/socials/threads/setters.ts
+var publisher = createPublisher({
+  name: "Threads",
+  getStatus: getThreadsContainerStatus,
+  createContainer: async (token, params) => readGraphID(
+    "Threads container",
+    await getThreadsData(token, "me/threads", {
+      params,
+      method: "POST"
+    })
+  ),
+  publish: async (token, creationID) => readGraphID(
+    "Threads publish",
+    await getThreadsData(token, "me/threads_publish", {
+      params: { creation_id: creationID },
+      method: "POST"
+    })
+  )
+});
+var mediaParams = (media) => ({
+  media_type: media ? media.type === "video" /* Video */ ? "VIDEO" : "IMAGE" : "TEXT",
+  image_url: media?.type === "photo" /* Photo */ ? media.url : void 0,
+  video_url: media?.type === "video" /* Video */ ? media.url : void 0,
+  alt_text: media?.altText
+});
+var createThreadsPost = async (token, input, replyToID) => {
+  const post = typeof input === "string" ? { text: input } : input;
+  const media = post.media ? [post.media].flat() : [];
+  const shared = {
+    text: post.text,
+    reply_to_id: post.replyToID || replyToID,
+    reply_control: post.replyControl
+  };
+  if (media.length > 1) {
+    const children = await publisher.createChildren(
+      token,
+      media.map((item) => mediaParams(item)),
+      post.wait
+    );
+    if (!children) return null;
+    return publisher.publish(
+      token,
+      { ...shared, media_type: "CAROUSEL", children: children.join(",") },
+      post.wait
+    );
+  }
+  return publisher.publish(
     token,
-    "me/threads_publish",
     {
-      creation_id
+      ...mediaParams(media[0]),
+      ...shared,
+      link_attachment: post.linkAttachment
     },
-    "POST"
-  ).then((res) => res?.id);
-}
-var createThreadsPost = async (token, text, reply_to_id) => {
-  const containerID = await createContainer(token, text, reply_to_id);
-  if (!containerID) return null;
-  await new Promise((resolve) => setTimeout(resolve, 2e3));
-  return publishContainer(token, containerID);
+    post.wait
+  );
 };
-var createThread = async (token, threads) => {
+var createThread = async (token, posts) => {
   const publishedIDs = [];
-  for (const thread of threads) {
-    const postID = await createThreadsPost(
-      token,
-      thread.split("\n").join("%0A"),
-      publishedIDs.at(-1)
-    );
+  for (const post of posts) {
+    const postID = await createThreadsPost(token, post, publishedIDs.at(-1));
     if (postID) publishedIDs.push(postID);
   }
   return publishedIDs[0];
 };
 export {
-  createContainer,
   createThread,
-  createThreadsPost,
-  publishContainer
+  createThreadsPost
 };